sparrow-entity 0.1.0 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 76e688bd5ae2f8719fc59ffff9a0bfd183066fd824749d6844ee82b1a8ae841d
4
- data.tar.gz: a3ed6511da567a4ebdf639e88c324a4827d8583c524c93e6c48ca4c944dff3fb
3
+ metadata.gz: beb7d32b5994be1e192e1fc9c926083f689e2f33e06d8d1442e8515bb2acf2bd
4
+ data.tar.gz: c3def87e14848442a4623b2c51efa26db39cbea941cea78088ae37a7391922bf
5
5
  SHA512:
6
- metadata.gz: 694719ed28c757b29df505ebc55b836561ae24aa6df84d51c6956e30dd99b8f84bc1eb79edd63af64c3c2fe6b2d25c4875386214f9c81e2c98584eafe1ecd354
7
- data.tar.gz: dd6f355238fe4a7b120dc35007a5cdf5cd27d22f5803d4b1c2a8f87984f82f896645489f82a94ccbbfc5e9cb937a9e62fcfc090fc23ab51b7097c6d51a86e099
6
+ metadata.gz: e2372baf98b1142bb765f54d8dcd4e38848deb64914e2673357040a4c2f8e1a17be00bbf93a8e0a846bf3acde80c184e34b05b73e0e039d0aa227e3ea7f5c36f
7
+ data.tar.gz: 023ba12cbee19301e366480ad2748a5eff648030ccf7f4b9ed23e2aaa0582da1b6b30e1a7dd98d9a8dba8bafc94dc3e520fde0e030707d5e7b54c92abf279595
data/.rubocop.yml CHANGED
@@ -5,6 +5,9 @@ AllCops:
5
5
  NewCops: enable
6
6
  SuggestExtensions: false
7
7
 
8
+ # 暂时无法添加验证
9
+ Gemspec/RequireMFA:
10
+ Enabled: false
8
11
  # 弱ruby版本的gem,所有目前不需要检测ruby版本
9
12
  Gemspec/RequiredRubyVersion:
10
13
  Enabled: false
data/Gemfile.lock CHANGED
@@ -1,7 +1,7 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- sparrow-entity (0.1.0)
4
+ sparrow-entity (0.1.4)
5
5
  activemodel
6
6
  activemodel_object_info (~> 0.2.0)
7
7
  activesupport
data/README.md ADDED
@@ -0,0 +1,152 @@
1
+ # Sparrow
2
+
3
+ Sparrow 用来快速实现在一个 Ruby 项目中引入实体处理非数据库可以映射的项目。特别是对于拆分为微服务的项目来说,由于大量数据基于其他服务获取到,而并不是直接来源于数据库,所以不能使用基于 **ActiveRecord::Base** 这样的类来处理具体数据实例。而 Sparrow 就提供了类似 ORM 式的使用方法来处理这些对象类。
4
+
5
+ ## 安装
6
+
7
+ 在你的项目中的 Gemfile 文件添加如下一行即可。建议保持最新版本以获取功能齐全的体验。
8
+
9
+ ```ruby
10
+ gem 'sparrow-entity', require: 'sparrow'
11
+ ```
12
+
13
+ 之后在你的项目文件夹下执行命令安装。
14
+
15
+ $ bundle
16
+
17
+ 或者也可以直接使用 gem 命令全局安装。
18
+
19
+ $ gem install sparrow-entity
20
+
21
+ ## 使用
22
+
23
+ ### 一般的使用方法
24
+
25
+ 安装之后尽可以在需要的时候随意创建自己的实体类,只要继承该 gem 提供的基础类即可。需要注意的是,如果你是在单纯的 Ruby 项目下使用,记得在使用前引入相关文件,比如:
26
+
27
+ ```ruby
28
+ # 使用本 gem 引入。如果是 Rails 项目则可省略。
29
+ require 'sparrow'
30
+
31
+ # 定义一个继承自 gem 基本实体类的自定义实体类
32
+ class MyEntity < Sparrow::Base
33
+ # 定义相关的属性和类型
34
+ field :id, Integer
35
+ field :family_name, String
36
+ field :given_name, String
37
+ field :gender, Integer
38
+ field :birthday, Date
39
+ field :nationality, String
40
+ # 也可以给与属性默认值,如果属性值本身无效时获取该属性会返回默认值
41
+ field :status, String, default: 'good'
42
+
43
+ # 定义具体的实例方法可以在之后使用
44
+ def full_name(last: :given, seperator: ' ')
45
+ val = [family_name, given_name]
46
+ val.reverse! if last == :family
47
+ val.join(seperator)
48
+ end
49
+ end
50
+ ```
51
+
52
+ 这样定义的一个类就具有了唯一标示 **id**,姓氏 **family_name**,名字 **given_name**,性别 **gender**,出生日期 **birthday** 和国籍 **nationality** 这几个属性,并且会在赋值和获取对应属性值时尝试自动将该属性设置转换为对应的数据类型。举例来说,比如给出一个可以被解析的日期字符串并赋值给出生日期属性,那么获取该属性值时会自动转化成定义属性时设定的 **Date** 类型的日期:
53
+
54
+ ```ruby
55
+ me = MyEntity.new(birthday: '2022-01-01')
56
+ me.birthday
57
+ # => <Date 2022年1月1日> 实例对象
58
+ ```
59
+
60
+ ### 布尔型属性
61
+
62
+ 当需要定义一个属性字段为布尔型时,可以使用本 gem 内置的 `Sparrow::Boolean` 作为类型定义即可。当赋予 **true** 值或者等价于(即使用 `present?` 判断为真)其值时被赋予真值,否则被赋予假值。同样的,如果没有对其进行赋值,则获取该字段属性会返回 **nil** 空值。
63
+
64
+ ```ruby
65
+ class OtherEntity < Sparrow::Base
66
+ field :married, Sparrow::Boolean
67
+ end
68
+
69
+ obj = OtherEntity.new
70
+ obj.married
71
+ # => nil
72
+
73
+ obj.married = true
74
+ obj.married
75
+ # => true
76
+
77
+ obj.married = ''
78
+ obj.married
79
+ # => false
80
+
81
+ obj.married = 'yes'
82
+ obj.married
83
+ # => true
84
+ ```
85
+
86
+ ### 赋值
87
+
88
+ 上例中也展示了为实体类的实例进行属性赋值的方式之一,即创建时指定属性名对应的值。当然也可以在创建后分别给属性赋值。
89
+
90
+ ```ruby
91
+ me.family_name = '张'
92
+ me.last_name = '三'
93
+ me.full_name(seperator: '')
94
+ # => "张三"
95
+ ```
96
+
97
+ ### 默认属性值
98
+
99
+ 在定义属性的时候可以跟着 `default` 命名参数给出默认值。当属性值为空或者无效时,获取属性的时候会返回默认值。
100
+
101
+ ```ruby
102
+ me.status
103
+ # => "good"
104
+ me.status = 'bad'
105
+ me.status
106
+ # => "bad"
107
+ ```
108
+
109
+ ### 基于 Rails 项目的使用方法
110
+
111
+ 如果你的项目是一个基于 Rails 框架的项目,那么在创建自己的实体时并不需要特别声明引入该 gem 对应的文件,因为 Rails 框架已经替你做好了一切。
112
+
113
+ 另外,使用 Rails 框架的项目还可以利用本 gem 提供的生成器(Generator)来方便快速生成一个新的实体类。
114
+
115
+ $ rails g sparrow:entity Post::Replay
116
+
117
+ 使用命令 Rails 生成器命令 `sparrow:entity` 会在你的项目根文件夹的 `app/entities` 路径下生成 `post/reply.rb` 的文件,文件也自动创建了好了继承类。
118
+
119
+ ```ruby
120
+ module Post
121
+ class Reply < Sparrow::Base
122
+ end
123
+ end
124
+ ```
125
+
126
+ 之后可以根据自己的需要修改生成的框架类的命名空间或者类的名称。
127
+
128
+ ### 内置的属性方法
129
+
130
+ 除了常规的 `attributes` 和 `attribute_names` 方法分别获取属性名和值的键值对以及属性名的数组外,本 gem 还内置了 [activemodel_object_info](https://rubygems.org/gems/activemodel_object_info) 这个 gem 辅助生成属性和值的键值对散列。具体用法请参考相关 gem 的说明文档。
131
+
132
+ ```ruby
133
+ OUTPUT = {
134
+ attributes: [
135
+ { name: :full_name, type: :method },
136
+ { name: :sex, as: :gender, type: :abstract, filter: ->(v) { v == 1 ? 'Male' : 'Female' } },
137
+ ],
138
+ }.freeze
139
+
140
+ me.instance_info(OUTPUT)
141
+ # => { full_name: "张三", sex: "Male" }
142
+ ```
143
+
144
+ ## 面向开发者
145
+
146
+ 内置 Rake 命令包括了控制台开启命令 `rake c` 或者 `rake console` 即可开启控制台模式。
147
+
148
+ 默认的 Rake 命令为单元测试命令,等同于 `bundle exec rspec` 命令的效果。
149
+
150
+ ## License
151
+
152
+ The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
@@ -0,0 +1,11 @@
1
+ Description:
2
+ Create a new sparrow entity class file that inherite from Sparrow::Base.
3
+
4
+ Example:
5
+ rails generate sparrow:entity MyNameSpace::MyEntity
6
+
7
+ will create files as below:
8
+ app
9
+ entities
10
+ my_name_space
11
+ my_entity.rb
@@ -0,0 +1,85 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sparrow
4
+ #
5
+ # 创建一个自定义的创建 Sparrow::Base 的类。
6
+ #
7
+ # @author Shiner <shiner527@hotmail.com>
8
+ #
9
+ class EntityGenerator < Rails::Generators::NamedBase
10
+ # 默认的引入应用的相对安装路径
11
+ TARGET_RELATIVE_PATH = 'app/entities'
12
+
13
+ # 单模组模板
14
+ MODULE_TEMPLATE = <<~MODULE.strip
15
+ module %{module_name}
16
+ %{module_content}
17
+ end
18
+ MODULE
19
+
20
+ # 单类模板
21
+ CLASS_TEMPLATE = <<~KLASS.strip
22
+ class %{class_name} < Sparrow::Base
23
+ #
24
+ # Useage:
25
+ #
26
+ # use field DSL to define attribute.
27
+ # like: <tt>field :name, String</tt> to define an string attribute called +name+.
28
+ #
29
+ end
30
+ KLASS
31
+
32
+ source_root File.expand_path('templates', __dir__)
33
+
34
+ #
35
+ # 复制模板文件到对应 Rails 项目中
36
+ #
37
+ def create_sparrow_class_file
38
+ # 如果存在命名空间,则分别生成对应模型
39
+ if class_path.present?
40
+ class_path.each_with_index do |sub, index|
41
+ @sub_paths = class_path[0..index]
42
+ parent_paths = @sub_paths.dup
43
+ parent_paths.pop
44
+ sub_path = ::File.join(TARGET_RELATIVE_PATH, parent_paths, "#{sub}.rb")
45
+ template 'module.rb.tt', sub_path
46
+ end
47
+ end
48
+
49
+ # 类文件最终路径
50
+ sparrow_file_path = ::File.join(TARGET_RELATIVE_PATH, class_path, "#{file_name}.rb")
51
+ # 类文件生成
52
+ template 'sparrow_entity.rb.tt', sparrow_file_path
53
+ end
54
+
55
+ private
56
+
57
+ def indent_level
58
+ @indent_level = @indent_level.blank? ? 0 : @indent_level + 1
59
+ end
60
+
61
+ def __module_content__(name, content)
62
+ MODULE_TEMPLATE % { module_name: name.camelize, module_content: indent(content, 2) }
63
+ end
64
+
65
+ def __class_content__
66
+ CLASS_TEMPLATE % { class_name: file_name.camelize }
67
+ end
68
+
69
+ def __class_body__
70
+ results = __class_content__
71
+ class_path.reverse.each { |sub| results = __module_content__(sub, results) } if class_path.present?
72
+ results << "\n"
73
+ results
74
+ end
75
+
76
+ def __module_body__(paths = [])
77
+ current = paths.shift
78
+ content = paths.size.positive? ? __module_body__(paths) : ''
79
+ result = current ? __module_content__(current, content) : ''
80
+ result = result.each_line.select(&:present?).join
81
+ result << "\n"
82
+ result
83
+ end
84
+ end
85
+ end
@@ -0,0 +1,3 @@
1
+ # frozen_string_literal: true
2
+
3
+ <%= __module_body__(@sub_paths) -%>
@@ -0,0 +1,3 @@
1
+ # frozen_string_literal: true
2
+
3
+ <%= __class_body__ -%>
@@ -0,0 +1,13 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sparrow
4
+ #
5
+ # 定义一个用来负责处理布尔值类型的对象类。
6
+ #
7
+ # @author Shiner <shiner527@hotmail.com>
8
+ #
9
+ class Boolean
10
+ # 定义一个空类来处理布尔值内容
11
+ DEFAULT_VALUE = true
12
+ end
13
+ end
@@ -80,6 +80,8 @@ module Sparrow
80
80
  val = value
81
81
  when ::String
82
82
  val = attr_class.parse(value)
83
+ val = val.localtime if attr_class.is_a?(::Time)
84
+ val = val.localtime.to_datetime if attr_class.is_a?(::DateTime)
83
85
  end
84
86
  instance_variable_set(instance_var_name, val)
85
87
  end
@@ -98,6 +100,11 @@ module Sparrow
98
100
  end
99
101
  instance_variable_set(instance_var_name, val)
100
102
  end
103
+ elsif attr_class == ::Sparrow::Boolean
104
+ # 如果是布尔值类型
105
+ define_method(setter_name) do |value|
106
+ instance_variable_set(instance_var_name, value.present?)
107
+ end
101
108
  else
102
109
  # 其他类型原封不动
103
110
  define_method(setter_name) do |value|
@@ -2,7 +2,7 @@
2
2
 
3
3
  module Sparrow
4
4
  # 当前版本号
5
- VERSION = '0.1.0'
5
+ VERSION = '0.1.4'
6
6
  # 当前综述
7
7
  SUMMARY = 'Provide an easy approach to build entity object for data that can not be reflected to database tables.'
8
8
  # 当前详述
data/lib/sparrow.rb CHANGED
@@ -4,6 +4,7 @@ require 'sparrow/version'
4
4
  require 'active_support'
5
5
  require 'active_model'
6
6
  require 'activemodel_object_info'
7
+ require 'sparrow/boolean'
7
8
  require 'sparrow/class_methods'
8
9
  require 'sparrow/base'
9
10
 
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: sparrow-entity
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.0
4
+ version: 0.1.4
5
5
  platform: ruby
6
6
  authors:
7
7
  - shiner
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2021-12-31 00:00:00.000000000 Z
11
+ date: 2022-01-10 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: activemodel
@@ -170,14 +170,19 @@ files:
170
170
  - Gemfile
171
171
  - Gemfile.lock
172
172
  - LICENSE
173
- - README
173
+ - README.md
174
174
  - Rakefile
175
175
  - bin/console
176
176
  - bin/setup
177
177
  - lib/config/locales/sparrow/base.en.yml
178
178
  - lib/config/locales/sparrow/base.zh-CN.yml
179
+ - lib/generators/sparrow/entity/USAGE
180
+ - lib/generators/sparrow/entity/entity_generator.rb
181
+ - lib/generators/sparrow/entity/templates/module.rb.tt
182
+ - lib/generators/sparrow/entity/templates/sparrow_entity.rb.tt
179
183
  - lib/sparrow.rb
180
184
  - lib/sparrow/base.rb
185
+ - lib/sparrow/boolean.rb
181
186
  - lib/sparrow/class_methods.rb
182
187
  - lib/sparrow/version.rb
183
188
  - sparrow.gemspec
data/README DELETED
@@ -1,43 +0,0 @@
1
- # Sparrow
2
-
3
- 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.
4
-
5
- TODO: Delete this and the text above, and describe your gem
6
-
7
- ## Installation
8
-
9
- Add this line to your application's Gemfile:
10
-
11
- ```ruby
12
- gem 'sparrow'
13
- ```
14
-
15
- And then execute:
16
-
17
- $ bundle
18
-
19
- Or install it yourself as:
20
-
21
- $ gem install sparrow
22
-
23
- ## Usage
24
-
25
- TODO: Write usage instructions here
26
-
27
- ## Development
28
-
29
- 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.
30
-
31
- 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).
32
-
33
- ## Contributing
34
-
35
- 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.
36
-
37
- ## License
38
-
39
- The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
40
-
41
- ## Code of Conduct
42
-
43
- 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).