arql 0.3.29 → 0.3.30

data/auto-set-id-before-save-zh_CN.org

@@ -0,0 +1,35 @@
+* 新建对象在保存之前自动设置 ID
+
+  对于非 =auto_increment= 的主键，那么可能希望在保存对象之前，为其设置一个唯一的 ID。可以这样做：
+
+  创建一个文件 =~/.arql.d/auto_gen_id.rb= ，内容如下：
+
+  #+BEGIN_SRC ruby
+    class ::ArqlModel
+      before_create do
+        if id.blank?
+          id_type = self.class.columns_hash['id'].sql_type.scan(/\w+/).first
+          case id_type
+          when 'bigint'
+            self.id = ::Arql::ID.long
+          when 'char'
+            self.id = ::Arql::ID.uuid
+          when 'varchar'
+            self.id = ::Arql::ID.uuid
+          end
+        end
+      end
+    end
+  #+END_SRC
+  
+   然后在 =~/.arql.d/init.rb= 中引入这个文件:
+
+   #+BEGIN_SRC ruby
+     load(File.absolute_path(File.dirname(__FILE__) + "/auto_set_id.rb"))
+   #+END_SRC
+
+   前提是，你的表的主键是 =id= 字段，且类型是 =bigint= 或 =char= 或 =varchar= 之一。
+
+   如果你的表的主键不是 =id= 字段，那么你需要修改上面的代码。
+
+   

data/auto-set-id-before-save.org

@@ -0,0 +1,33 @@
+* Set ID automatically for new objects before saving
+
+  For primary keys that are not =auto_increment=, you may want to set a unique ID for the object before saving it. You can do this:
+
+  Create a file =~/.arql.d/auto_gen_id.rb= with the following content:
+
+  #+BEGIN_SRC ruby
+    class ::ArqlModel
+      before_create do
+        if id.blank?
+          id_type = self.class.columns_hash['id'].sql_type.scan(/\w+/).first
+          case id_type
+          when 'bigint'
+            self.id = ::Arql::ID.long
+          when 'char'
+            self.id = ::Arql::ID.uuid
+          when 'varchar'
+            self.id = ::Arql::ID.uuid
+          end
+        end
+      end
+    end
+  #+END_SRC
+
+  Then in =~/.arql.d/init.rb=, require this file:
+
+  #+BEGIN_SRC ruby
+    load(File.absolute_path(File.dirname(__FILE__) + "/auto_set_id.rb"))
+  #+END_SRC
+
+  The prerequisite is that the primary key of your table is the =id= field, and the type is one of =bigint=, =char= or =varchar=.
+
+  If the primary key of your table is not the =id= field, you need to modify the code above.

data/custom-configurations-zh_CN.org

@@ -0,0 +1,50 @@
+* 配置文件中的自定义配置项
+
+  你可以在配置文件 (如默认的 =~/.arql.yaml= / =~/.arql.d/init.yaml= ) 中定义自己的配置项，然后在代码中通过 =Arql::App.config["CONF_KEY"]-= 来获取配置项的值。
+
+  例如，假设系统对 BankAccount 表的 =account_no= 字段进行了加密，你可以在配置文件中定义加密的密钥：
+
+  #+BEGIN_SRC yaml
+    dev:
+      <<: *default
+      host: 127.0.0.1
+      port: 3306
+      username: test
+      password: test123456
+      database: devel 
+      encrypt_key: "1234567890abcdef"
+  #+END_SRC
+
+  然后你可以在 Initialzier 代码 (=~/.arql.rb= / =~/.arql.d/init.rb=) 中读取配置项的值：
+
+  #+BEGIN_SRC ruby
+    class BankAccount
+    
+      def self.encrypt_account_no(account_no)
+        cipher = OpenSSL::Cipher.new('AES-128-ECB')
+        cipher.encrypt
+        cipher.key = Arql::App.config["encrypt_key"]
+        encrypted = cipher.update(account_no) + cipher.final
+        encrypted.unpack('H*').first
+      end
+    
+      def self.decrypt_account_no(encrypted_account_no)
+        cipher = OpenSSL::Cipher.new('AES-128-ECB')
+        cipher.decrypt
+        cipher.key = Arql::App.config["encrypt_key"]
+        decrypted = cipher.update([encrypted_account_no].pack('H*')) + cipher.final
+        decrypted
+      end
+    
+    
+      # 从数据库查询出数据之后，自动解密 account_no 字段
+      after_find do
+        self.password = decrypt_account_no(self.password)
+      end
+    
+      # 保存数据之前，自动加密 account_no 字段
+      before_save do
+        self.password = encrypt_account_no(self.password)
+      end
+    end
+  #+END_SRC

data/custom-configurations.org

@@ -0,0 +1,54 @@
+* Additional config items in Configuration File
+
+  You can define your own configuration items in the configuration file (such as the default =~/.arql.yaml= /
+  =~/.arql.d/init.yaml=), and then get the value of the configuration item in the code through
+  =Arql::App.config["CONF_KEY"]=.
+
+  For example, suppose the system encrypts the =account_no= field of the BankAccount table, you can define the
+  encryption key in the configuration file:
+
+  #+BEGIN_SRC yaml
+    dev:
+      <<: *default
+      host: 127.0.0.1
+      port: 3306
+      username: test
+      password: test123456
+      database: devel 
+      encrypt_key: "1234567890abcdef"
+  #+END_SRC
+
+  Then you can read the value of the configuration item in the Initialzier code (=~/.arql.rb= /
+  =~/.arql.d/init.rb=):
+  
+  #+BEGIN_SRC ruby
+    class BankAccount
+    
+      def self.encrypt_account_no(account_no)
+        cipher = OpenSSL::Cipher.new('AES-128-ECB')
+        cipher.encrypt
+        cipher.key = Arql::App.config["encrypt_key"]
+        encrypted = cipher.update(account_no) + cipher.final
+        encrypted.unpack('H*').first
+      end
+    
+      def self.decrypt_account_no(encrypted_account_no)
+        cipher = OpenSSL::Cipher.new('AES-128-ECB')
+        cipher.decrypt
+        cipher.key = Arql::App.config["encrypt_key"]
+        decrypted = cipher.update([encrypted_account_no].pack('H*')) + cipher.final
+        decrypted
+      end
+    
+    
+      # After querying the data from the database, automatically decrypt the account_no field
+      after_find do
+        self.password = decrypt_account_no(self.password)
+      end
+    
+      # Before saving the data, automatically encrypt the account_no field
+      before_save do
+        self.password = encrypt_account_no(self.password)
+      end
+    end
+  #+END_SRC

data/define-associations-zh_CN.org

@@ -0,0 +1,38 @@
+* 在 Initializer 文件中定义关联关系
+
+  可以在 Initializer 文件中定义关联关系，Arql 启动后会首先根据数据库 Schema 生成模型类，然后加载 Initializer 文件。
+
+  Initializer 文件是一个 Ruby 文件，因此可以在其中定义关联关系，例如：
+
+  #+BEGIN_SRC ruby
+    class Student
+      has_many :courses, foreign_key: :student_id, class_name: 'Course'
+      belongs_to :school, foreign_key: :school_id, class_name: 'School'
+
+      has_and_belongs_to_many :teachers, join_table: 'students_teachers', foreign_key: :student_id, association_foreign_key: :teacher_id, class_name: 'Teacher'
+    end
+
+    class Course
+      belongs_to :student, foreign_key: :student_id, class_name: 'Student'
+    end
+
+    class School
+      has_many :students, foreign_key: :school_id, class_name: 'Student'
+    end
+
+    class Teacher
+      has_and_belongs_to_many :students, join_table: 'students_teachers', foreign_key: :teacher_id, association_foreign_key: :student_id, class_name: 'Student'
+    end
+  #+END_SRC
+
+  1. =has_one= 表明此表是一对一关系的属主
+  2. =belongs_to= 表明此表是一对多或一对一关系的从属方
+  3. =has_and_belongs_to_many= 表明此表是多对多关系的其中一方
+  4. =class_name= 表明此关联关系对应的对方的 Model 类名（Model 类名实际就是表名的 CamelCase 形式）
+  5. =foreign_key= 表明此关联关系中，从属表一侧的关联字段名
+  6. =primary_key= 表明此关联关系中，属主表一侧的关联字段名
+  7. =join_table= 在多对多关系中，表明关联两个表的中间表名
+  8. =association_foreign_key= 在多对多关系中，表明对方 Model 在中间表中的关联字段名
+
+  可以参考： https://guides.rubyonrails.org/association_basics.html
+

data/define-associations.org

@@ -0,0 +1,37 @@
+* Define associations in Initializers
+
+  You can define associations in Initializers. Arql will generate model classes based on the database schema when it starts, and then load the Initializer file.
+
+  The Initializer file is a Ruby file, so you can define associations in it, for example:
+
+  #+BEGIN_SRC ruby
+    class Student
+      has_many :courses, foreign_key: :student_id, class_name: 'Course'
+      belongs_to :school, foreign_key: :school_id, class_name: 'School'
+
+      has_and_belongs_to_many :teachers, join_table: 'students_teachers', foreign_key: :student_id, association_foreign_key: :teacher_id, class_name: 'Teacher'
+    end
+
+    class Course
+      belongs_to :student, foreign_key: :student_id, class_name: 'Student'
+    end
+
+    class School
+      has_many :students, foreign_key: :school_id, class_name: 'Student'
+    end
+
+    class Teacher
+      has_and_belongs_to_many :students, join_table: 'students_teachers', foreign_key: :teacher_id, association_foreign_key: :student_id, class_name: 'Student'
+    end
+  #+END_SRC
+
+  1. =has_one= indicates that this table is the owner of a one-to-one relationship
+  2. =belongs_to= indicates that this table is the dependent side of a one-to-many or one-to-one relationship
+  3. =has_and_belongs_to_many= indicates that this table is one of the many-to-many relationships
+  4. =class_name= indicates the Model class name of the corresponding relationship (the Model class name is actually the CamelCase form of the table name)
+  5. =foreign_key= indicates the name of the association field on the dependent side of the association
+  6. =primary_key= indicates the name of the association field on the owner side of the association
+  7. =join_table= in many-to-many relationships, indicates the name of the intermediate table that associates the two tables
+  8. =association_foreign_key= in many-to-many relationships, indicates the association field name of the other Model in the intermediate table
+
+  You can refer to: https://guides.rubyonrails.org/association_basics.html

data/fuzzy-field-query-zh_CN.org

@@ -0,0 +1,165 @@
+* 字段名 Fuzzy 化查询
+
+  有时候系统的字段名非常冗长，我们可以使用 Fuzzy 化查询来简化查询，例如，有一个字段名为 =system_user_nickname= ，我们希望可
+  以使用 =nickname= 来查询。甚至是 =nick= 或者 =nina= 也可以查询到。
+
+  #+BEGIN_SRC ruby
+    user = User.find_by_nick('张三')  # select * from users where system_user_nickname = '张三'
+    user = User.find_by_nina('张三')  # select * from users where system_user_nickname = '张三'
+    
+    name = user.nina  # 返回 user.system_user_nickname
+  #+END_SRC
+
+  可以使用如下代码实现：
+
+  创建一个文件 =~/.arql.d/fuzzy_field_query.rb= ，内容如下：
+
+  #+BEGIN_SRC ruby
+    module ActiveRecord
+      module Core
+        def inspect
+          # We check defined?(@attributes) not to issue warnings if the object is
+          # allocated but not initialized.
+          inspection = if defined?(@attributes) && @attributes
+                         self.class.attribute_names.collect do |name|
+              if has_attribute?(name)
+                attr = _read_attribute(name)
+                value = if attr.nil?
+                          attr.inspect
+                        else
+                          attr = format_for_inspect(attr)
+                          inspection_filter.filter_param(name, attr)
+                        end
+                "#{name}: #{value}"
+              elsif has_attribute?(name.upcase)
+                attr = _read_attribute(name.upcase)
+                value = if attr.nil?
+                          attr.inspect
+                        else
+                          attr = format_for_inspect(attr)
+                          inspection_filter.filter_param(name.upcase, attr)
+                        end
+                "#{name}: #{value}"
+              end
+            end.compact.join(", ")
+                       else
+                         "not initialized"
+                       end
+    
+          "#<#{self.class} #{inspection}>"
+        end
+    
+        def pretty_print(pp)
+          return super if custom_inspect_method_defined?
+          pp.object_address_group(self) do
+            if defined?(@attributes) && @attributes
+              attr_names = self.class.attribute_names.select { |name| has_attribute?(name) || has_attribute?(name.upcase) }
+              pp.seplist(attr_names, proc { pp.text "," }) do |attr_name|
+                pp.breakable " "
+                pp.group(1) do
+                  pp.text attr_name
+                  pp.text ":"
+                  pp.breakable
+                  if has_attribute?(attr_name)
+                    value = _read_attribute(attr_name)
+                    value = inspection_filter.filter_param(attr_name, value) unless value.nil?
+                  elsif has_attribute?(attr_name.upcase)
+                    value = _read_attribute(attr_name.upcase)
+                    value = inspection_filter.filter_param(attr_name.upcase, value) unless value.nil?
+                  end
+                  pp.pp value
+                end
+              end
+            else
+              pp.breakable " "
+              pp.text "not initialized"
+            end
+          end
+        end
+    
+        module ClassMethods
+          def find_by(*args) # :nodoc:
+            return super if scope_attributes? || reflect_on_all_aggregations.any? ||
+              columns_hash.key?(inheritance_column) && !base_class?
+    
+            hash = args.first
+    
+            return super if !(Hash === hash) || hash.values.any? { |v|
+              StatementCache.unsupported_value?(v)
+            }
+    
+            # We can't cache Post.find_by(author: david) ...yet
+            return super unless hash.keys.all? { |k|
+              fuzzy_regexp = Regexp.new(k.to_s.chars.join('.*'))
+              columns_hash.has_key?(k.to_s) || columns_hash.keys.any? { |e| e =~ fuzzy_regexp }
+            }
+    
+            keys = hash.keys
+    
+            columns_keys = columns_hash.keys
+    
+            keys.map! do |k|
+              k = k.to_s
+              fuzzy_regexp = Regexp.new(k.chars.join('.*'))
+              columns_keys.find { |ck| ck == k }&.to_sym ||
+                columns_keys.find { |ck| ck.split('_').map(&:first).join().start_with?(k) }&.to_sym ||
+                columns_keys.find { |ck| ck =~ fuzzy_regexp }&.to_sym
+            end
+    
+            statement = cached_find_by_statement(keys) { |params|
+              wheres = keys.each_with_object({}) { |param, o|
+                o[param] = params.bind
+              }
+              where(wheres).limit(1)
+            }
+            begin
+              statement.execute(hash.values, connection)&.first
+            rescue TypeError
+              raise ActiveRecord::StatementInvalid
+            end
+          end
+        end
+      end
+    
+      module DynamicMatchers
+        class Method
+          def valid?
+            attribute_names.all? do |name|
+              name = name.downcase unless name == name.downcase
+              fuzzy_regexp = Regexp.new(name.to_s.chars.join('.*'))
+              model.columns_hash[name] ||
+                model.reflect_on_aggregation(name.to_sym) ||
+                model.column_names.any? { |e| e =~ fuzzy_regexp }
+            end
+          end
+        end
+      end
+    end
+    
+    module ActiveModel
+      module AttributeMethods
+        def method_missing(method, *args, &block)
+          if respond_to_without_attributes?(method, true)
+            super
+          else
+            match = matched_attribute_method(method.to_s)
+            unless match
+              fuzzy_regexp = Regexp.new(method.to_s.chars.join('.*'))
+              fuzzy_column = attribute_names.find { |ck| ck.split('_').map(&:first).join().start_with?(method.to_s) } ||
+                attribute_names.find { |ck| ck =~ fuzzy_regexp }
+              match = matched_attribute_method(fuzzy_column) if fuzzy_column
+            end
+            match ? attribute_missing(match, *args, &block) : super
+          end
+        end
+      end
+    end
+    
+  #+END_SRC
+  
+
+   然后在 =~/.arql.d/init.rb= 中引入这个文件:
+
+   #+BEGIN_SRC ruby
+     load(File.absolute_path(File.dirname(__FILE__) + "/fuzzy_field_query.rb"))
+   #+END_SRC

data/fuzzy-field-query.org

@@ -0,0 +1,165 @@
+* Fuzzy Field Query
+
+  Sometimes the field name of the system is very long, we can use Fuzzy Field Query to simplify the query, for example,
+  there is a field name =system_user_nickname=, we hope to use =nickname= to query. Even =nick= or =nina= can also be
+  queried.
+
+  #+BEGIN_SRC ruby
+    user = User.find_by_nick('张三')  # select * from users where system_user_nickname = '张三'
+    user = User.find_by_nina('张三')  # select * from users where system_user_nickname = '张三'
+    
+    name = user.nina  # return user.system_user_nickname
+  #+END_SRC
+
+  You can implement it as follows:
+
+  Create a file =~/.arql.d/fuzzy_field_query.rb=, the content is as follows:
+  
+  #+BEGIN_SRC ruby
+    module ActiveRecord
+      module Core
+        def inspect
+          # We check defined?(@attributes) not to issue warnings if the object is
+          # allocated but not initialized.
+          inspection = if defined?(@attributes) && @attributes
+                         self.class.attribute_names.collect do |name|
+              if has_attribute?(name)
+                attr = _read_attribute(name)
+                value = if attr.nil?
+                          attr.inspect
+                        else
+                          attr = format_for_inspect(attr)
+                          inspection_filter.filter_param(name, attr)
+                        end
+                "#{name}: #{value}"
+              elsif has_attribute?(name.upcase)
+                attr = _read_attribute(name.upcase)
+                value = if attr.nil?
+                          attr.inspect
+                        else
+                          attr = format_for_inspect(attr)
+                          inspection_filter.filter_param(name.upcase, attr)
+                        end
+                "#{name}: #{value}"
+              end
+            end.compact.join(", ")
+                       else
+                         "not initialized"
+                       end
+    
+          "#<#{self.class} #{inspection}>"
+        end
+    
+        def pretty_print(pp)
+          return super if custom_inspect_method_defined?
+          pp.object_address_group(self) do
+            if defined?(@attributes) && @attributes
+              attr_names = self.class.attribute_names.select { |name| has_attribute?(name) || has_attribute?(name.upcase) }
+              pp.seplist(attr_names, proc { pp.text "," }) do |attr_name|
+                pp.breakable " "
+                pp.group(1) do
+                  pp.text attr_name
+                  pp.text ":"
+                  pp.breakable
+                  if has_attribute?(attr_name)
+                    value = _read_attribute(attr_name)
+                    value = inspection_filter.filter_param(attr_name, value) unless value.nil?
+                  elsif has_attribute?(attr_name.upcase)
+                    value = _read_attribute(attr_name.upcase)
+                    value = inspection_filter.filter_param(attr_name.upcase, value) unless value.nil?
+                  end
+                  pp.pp value
+                end
+              end
+            else
+              pp.breakable " "
+              pp.text "not initialized"
+            end
+          end
+        end
+    
+        module ClassMethods
+          def find_by(*args) # :nodoc:
+            return super if scope_attributes? || reflect_on_all_aggregations.any? ||
+              columns_hash.key?(inheritance_column) && !base_class?
+    
+            hash = args.first
+    
+            return super if !(Hash === hash) || hash.values.any? { |v|
+              StatementCache.unsupported_value?(v)
+            }
+    
+            # We can't cache Post.find_by(author: david) ...yet
+            return super unless hash.keys.all? { |k|
+              fuzzy_regexp = Regexp.new(k.to_s.chars.join('.*'))
+              columns_hash.has_key?(k.to_s) || columns_hash.keys.any? { |e| e =~ fuzzy_regexp }
+            }
+    
+            keys = hash.keys
+    
+            columns_keys = columns_hash.keys
+    
+            keys.map! do |k|
+              k = k.to_s
+              fuzzy_regexp = Regexp.new(k.chars.join('.*'))
+              columns_keys.find { |ck| ck == k }&.to_sym ||
+                columns_keys.find { |ck| ck.split('_').map(&:first).join().start_with?(k) }&.to_sym ||
+                columns_keys.find { |ck| ck =~ fuzzy_regexp }&.to_sym
+            end
+    
+            statement = cached_find_by_statement(keys) { |params|
+              wheres = keys.each_with_object({}) { |param, o|
+                o[param] = params.bind
+              }
+              where(wheres).limit(1)
+            }
+            begin
+              statement.execute(hash.values, connection)&.first
+            rescue TypeError
+              raise ActiveRecord::StatementInvalid
+            end
+          end
+        end
+      end
+    
+      module DynamicMatchers
+        class Method
+          def valid?
+            attribute_names.all? do |name|
+              name = name.downcase unless name == name.downcase
+              fuzzy_regexp = Regexp.new(name.to_s.chars.join('.*'))
+              model.columns_hash[name] ||
+                model.reflect_on_aggregation(name.to_sym) ||
+                model.column_names.any? { |e| e =~ fuzzy_regexp }
+            end
+          end
+        end
+      end
+    end
+    
+    module ActiveModel
+      module AttributeMethods
+        def method_missing(method, *args, &block)
+          if respond_to_without_attributes?(method, true)
+            super
+          else
+            match = matched_attribute_method(method.to_s)
+            unless match
+              fuzzy_regexp = Regexp.new(method.to_s.chars.join('.*'))
+              fuzzy_column = attribute_names.find { |ck| ck.split('_').map(&:first).join().start_with?(method.to_s) } ||
+                attribute_names.find { |ck| ck =~ fuzzy_regexp }
+              match = matched_attribute_method(fuzzy_column) if fuzzy_column
+            end
+            match ? attribute_missing(match, *args, &block) : super
+          end
+        end
+      end
+    end
+    
+  #+END_SRC
+
+  Then introduce this file in =~/.arql.d/init.rb=:
+
+  #+BEGIN_SRC ruby
+    load(File.absolute_path(File.dirname(__FILE__) + "/fuzzy_field_query.rb"))
+  #+END_SRC