arql 0.3.30 → 0.4.0

data/simple-active-record-guide-zh_CN.org

@@ -0,0 +1,83 @@
+* ActiveRecord 简明教程
+
+  ActiveRecord 是 Rails 中的 ORM 框架，它将数据库表映射到 Ruby 对象，让我们可以通过 Ruby 对象来操作数据库。
+
+  
+** 定义模型类
+
+  模型类是继承自 ActiveRecord::Base 的类，它们是数据库中的表在 Ruby 语言中的映射。
+
+  #+BEGIN_SRC ruby
+  class User < ActiveRecord::Base
+  end
+  #+END_SRC
+
+  而 User 对象的属性和数据库表的字段的对应关系，是 ActiveRecord 根据数据库中的表信息，自动完成的。
+
+  在 Arql 中，模型类的定义是 Arql 根据数据库表的表信息自动生成的，所以我们不需要像这里一样手动定义模型类。
+   
+** 定义关联关系
+
+   在 ActiveRecord 中，我们可以通过 has_many, belongs_to, has_one 等方法来定义模型类之间的关联关系。
+
+   - =has_many= 表明此表是一对多关系的“一”方
+   - =has_one= 表明此表是一对一关系的属主
+   - =belongs_to= 表明此表是一对多或一对一关系的从属方
+   - =has_and_belongs_to_many= 表明此表是多对多关系的其中一方
+   
+
+   使用 Arql 查询数据库时，我们希望也可以通过定义好的关联关系来查询数据。
+
+   例如，我们有两个模型类 User 和 Post，User 有多个 Post，Post 属于一个 User, 如果我们希望查询张三的所有文章，
+
+   在不使用关联关系的情况下，我们需要这样查询：
+
+   #+BEGIN_SRC ruby
+     user = User.find_by(name: '张三')
+     posts = Post.where(user_id: user.id)
+   #+END_SRC
+
+   而如果我们定义了关联关系，我们可以这样查询：
+
+    #+BEGIN_SRC ruby
+      user = User.find_by(name: '张三')
+      posts = user.posts
+    #+END_SRC
+
+    关联关系是在模型类中定义的，而 Arql 中模型类是 Arql 替我们自动生成的，那么我们要在哪里定义关联关系呢？
+
+    别忘了 Ruby 的类是可以重新打开的，我们可以在 Arql 中重新打开模型类，定义关联关系:
+
+    #+BEGIN_SRC ruby
+    class User < ActiveRecord::Base
+      has_many :posts
+    end
+    #+END_SRC
+
+    像 has_many, belongs_to, has_one 这样的方法，ActiveRecord 会根据默认的规则，来关联关系关联到的是哪个表的哪个字段。这也就是 Rails 中所谓的约定大于配置的体现。 
+
+    使用 Arql 查询既有系统的数据库时，数据库中的表、字段名称往往不符合 Rails 的规则约定，这时我们可以通过传递参数来指定关联关系的关联字段：
+
+    #+BEGIN_SRC ruby
+    class User < ActiveRecord::Base
+      has_many :posts, foreign_key: 'author_id', class_name: 'Article', primary_key: 'uid'
+    end
+    #+END_SRC
+
+    =has_many=, =belongs_to=, =has_one= 方法常用的参数如下：
+
+    - =class_name=: 表明此关联关系对应的对方的 Model 类名
+    - =foreign_key=: 表明此关联关系中，从属表一侧的关联字段名
+    - =primary_key=: 表明此关联关系中，属主表一侧的关联字段名
+    - =join_table=: 在多对多关系中，表明关联两个表的中间表名
+    - =association_foreign_key=: 在多对多关系中，表明对方 Model 在中间表中的关联字段名
+
+** 简单 CRUD
+
+   参考：https://guides.rubyonrails.org/active_record_querying.html
+
+** 参考
+
+   - https://guides.rubyonrails.org/active_record_basics.html
+   - https://guides.rubyonrails.org/active_record_querying.html
+   - https://guides.rubyonrails.org/association_basics.html

data/simple-pry-guides-zh_CN.org

@@ -0,0 +1,114 @@
+* Pry 简明教程
+
+** Pry 是什么？
+
+    和 Python 一样，Ruby 也有自己的 REPL 工具，叫做 irb（Interactive Ruby）。
+    
+    Pry 是另外一个功能更加强大的 Ruby REPL 工具，它可以让你在 Ruby REPL 中做很多事情，比如查看源码、查看文档、调试等等。
+
+    Arql 的主要功能就是基于 Pry 实现的，所以你可以把 Pry 当做 Arql 的一个子集。Pry 的命令和功能在 Arql 中都是可以使用的。而且 Arql 还提供了一些额外的 Pry 命令。
+
+
+    当然也可以单独安装和使用 Pry。
+    
+   
+** 单独安装 Pry
+
+   #+BEGIN_EXAMPLE
+    $ gem install pry
+   #+END_EXAMPLE
+
+   Pry 本身也支持扩展，你可以安装一些 Pry 的插件，比如 pry-doc、pry-byebug 等等。
+
+   #+BEGIN_EXAMPLE
+    $ gem install pry-doc
+    $ gem install pry-byebug
+   #+END_EXAMPLE
+
+   
+** 单独使用 Pry
+
+   #+BEGIN_EXAMPLE
+    $ pry
+   #+END_EXAMPLE
+
+   
+** 常用的 Pry 命令
+
+   
+*** 查看帮助
+
+   #+BEGIN_EXAMPLE
+    [1] pry(main)> help
+   #+END_EXAMPLE
+
+   
+*** 查看变量
+
+   #+BEGIN_EXAMPLE
+    [2] pry(main)> ls
+   #+END_EXAMPLE
+
+   
+*** 查看一个实例方法的源码
+
+   #+BEGIN_EXAMPLE
+    [3] pry(main)> show-source ActiveRecord::Base#save
+   #+END_EXAMPLE
+
+   
+*** 查看一个实例方法的文档
+
+   #+BEGIN_EXAMPLE
+    [4] pry(main)> show-doc ActiveRecord::Base#save
+   #+END_EXAMPLE
+
+
+*** 查看一个类的的源码
+
+   #+BEGIN_EXAMPLE
+    [5] pry(main)> show-source ActiveRecord::Base
+   #+END_EXAMPLE
+
+   
+*** 查看一个类的文档
+
+   #+BEGIN_EXAMPLE
+    [6] pry(main)> show-doc ActiveRecord::Base
+   #+END_EXAMPLE
+
+   
+*** 在 Pry 中直接修改代码
+
+    你甚至可以在 Pry 中用 edit 命令直接修改代码，然后 Pry 会自动保存修改后的代码到一个临时文件中，然后你可以在 Pry 中直接调用修改后的代码。
+
+    #+BEGIN_EXAMPLE
+      [7] pry(main)> edit ActiveRecord::Base#save
+    #+END_EXAMPLE
+    
+** 分号
+
+   在 Ruby 语言中， 行尾的分号是可以省略的。
+
+   
+   Pry 中每次执行一个 Ruby 表达式，都会自动打印出这个表达式的值：
+
+    #+BEGIN_EXAMPLE
+      [7] pry(main)> user.posts = Post.all
+      => [#<Post id: 1, title: "Hello World", content: "Hello World", created_at: "2016 -12-12 12:12:12", updated_at: "2016-12-12 12:12:12">,
+          #<Post id: 2, title: "Hello Ruby", content: "Hello Ruby", created_at: "2016-12-12 12:12:12", updated_at: "2016-12-12 12:12:12">,
+          ... ...]
+    #+END_EXAMPLE
+
+    这是通过调用 Ruby 的 表达式的值对象的 inspect 方法 (Object#inspect 方法)实现的。如果你不想打印出这个值，可以在表达式后面加上分号：
+
+    #+BEGIN_EXAMPLE
+      [8] pry(main)> user.posts = Post.all;
+    #+END_EXAMPLE
+
+    我们知道在 ActiveRecord 中，像 =User.where(gender: 'Male')= 这样的表达式，返回结果是一个 ActiveRecord::Relation 对象，而不是一个数组。
+    这样设计的目的是为了支持 Lazy Loading，只有在需要的时候才会去执行 SQL 查询。但是当我们在 Pry 中直接对 =User.where(gender: 'Male')= 的时候，却发现
+    它立即执行了 SQL 查询，并且输出的是一个数组对象；这就是因为 Pry 在打印对象的时候，会调用对象的 inspect 方法，而 ActiveRecord::Relation 对象的 inspect 方法
+    会立即执行 SQL 查询并返回一个数组对象。如果你不想立即执行 SQL 查询，就可以在表达式后面加上分号。
+
+

data/sql-log-zh_CN.org

@@ -7,13 +7,18 @@
   创建一个文件 =~/.arql.d/sql_log.rb= ，内容如下：
 
   #+BEGIN_SRC ruby
-    unless Arql::App.config[:append_sql]
+    unless Arql::App.instance.options.append_sql
       log_root_dir = File.expand_path('~/.arql.d/logs')
-      log_dir = "#{log_root_dir}/%s" % Arql::App.env
+      if Arql::App.instance.environments.present?
+        log_dir = "#{log_root_dir}/%s" % Arql::App.instance.environments.join('_')
+      elsif File.file?(Arql::App.instance.options[:database])
+        log_dir = "#{log_root_dir}/%s" % File.basename(Arql::App.instance.options[:database])
+      end
+    
       FileUtils.mkdir_p(log_dir)
       now = Time.now
       log_file = "#{log_dir}/%s.%s.%s.log" % [Time.now.strftime('%Y_%m%d_%H%M%S'), `hostname -s`.chomp.downcase, Process.pid]
-      Arql::App.config[:append_sql] = log_file
+      Arql::App.instance.options.append_sql = log_file
     
       lfile = File.new(log_file, 'a')
       lfile.sync = true

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: arql
 version: !ruby/object:Gem::Version
-  version: 0.3.30
+  version: 0.4.0
 platform: ruby
 authors:
 - Liu Xiang
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-04-12 00:00:00.000000000 Z
+date: 2024-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mysql2
@@ -334,20 +334,21 @@ files:
 - lib/arql/commands/redefine.rb
 - lib/arql/commands/sandbox.rb
 - lib/arql/commands/show_sql.rb
-- lib/arql/commands/table.rb
-- lib/arql/commands/vd.rb
 - lib/arql/concerns.rb
 - lib/arql/concerns/global_data_definition.rb
+- lib/arql/concerns/model_extension.rb
 - lib/arql/concerns/table_data_definition.rb
-- lib/arql/connection.rb
 - lib/arql/definition.rb
 - lib/arql/ext.rb
 - lib/arql/ext/active_record/connection_adapters/abstract_mysql_adapter.rb
 - lib/arql/ext/active_record/connection_adapters/postgresql/schema_statements.rb
+- lib/arql/ext/active_record/relation.rb
+- lib/arql/ext/active_record/result.rb
 - lib/arql/ext/array.rb
 - lib/arql/ext/hash.rb
 - lib/arql/ext/kernel.rb
 - lib/arql/ext/object.rb
+- lib/arql/ext/ransack/search.rb
 - lib/arql/ext/string.rb
 - lib/arql/ext/time.rb
 - lib/arql/id.rb
@@ -360,6 +361,9 @@ files:
 - lib/arql/version.rb
 - oss-files-zh_CN.org
 - oss-files.org
+- ruby-guides-for-java-developer-zh_CN.org
+- simple-active-record-guide-zh_CN.org
+- simple-pry-guides-zh_CN.org
 - sql-log-zh_CN.org
 - sql-log.org
 homepage: https://github.com/lululau/arql

data/lib/arql/commands/table.rb

@@ -1,55 +0,0 @@
-require 'terminal-table'
-
-module Arql::Commands
-  module Table
-    class << self
-      def get_table_name(name)
-        name = name.to_s
-        return name if name =~ /^[a-z]/
-        if Object.const_defined?(name)
-          klass = Object.const_get(name)
-          return klass.table_name if klass < ActiveRecord::Base
-        end
-        name
-      end
-
-      def table_info_table(table_name)
-        Terminal::Table.new do |t|
-          table_info(table_name).each { |row| t << (row || :separator) }
-        end
-      end
-
-      def table_info(table_name)
-        t = []
-        t << ['PK', 'Name', 'SQL Type', 'Ruby Type', 'Limit', 'Precision', 'Scale', 'Default', 'Nullable', 'Comment']
-        t << nil
-        connection = ::ActiveRecord::Base.connection
-        connection.columns(table_name).each do |column|
-          pk = if [connection.primary_key(table_name)].flatten.include?(column.name)
-                 'Y'
-               else
-                 ''
-               end
-          t << [pk, column.name, column.sql_type,
-                column.sql_type_metadata.type, column.sql_type_metadata.limit || '',
-                column.sql_type_metadata.precision || '', column.sql_type_metadata.scale || '', column.default || '',
-                column.null, column.comment || '']
-        end
-        t
-      end
-    end
-
-    Pry.commands.block_command 't' do |name|
-      table_name = Table::get_table_name(name)
-      puts
-      puts "Table: #{table_name}"
-      puts Table::table_info_table(table_name)
-    end
-  end
-end
-
-module Kernel
-  def table(name)
-    Arql::Commands::Table::table_info(Arql::Commands::Table::get_table_name(name))
-  end
-end

data/lib/arql/commands/vd.rb

@@ -1,46 +0,0 @@
-require 'arql/vd'
-
-module Arql::Commands
-  module VD
-    class << self
-      def get_table_name(name)
-        name = name.to_s
-        return name if name =~ /^[a-z]/
-        if Object.const_defined?(name)
-          klass = Object.const_get(name)
-          return klass.table_name if klass < ActiveRecord::Base
-        end
-        name
-      end
-
-      def table_info_vd(table_name)
-        Arql::VD.new do |vd|
-          table_info(table_name).each { |row| vd << row }
-        end
-      end
-
-      def table_info(table_name)
-        t = []
-        t << ['PK', 'Name', 'SQL Type', 'Ruby Type', 'Limit', 'Precision', 'Scale', 'Default', 'Nullable', 'Comment']
-        connection = ::ActiveRecord::Base.connection
-        connection.columns(table_name).each do |column|
-          pk = if [connection.primary_key(table_name)].flatten.include?(column.name)
-                 'Y'
-               else
-                 ''
-               end
-          t << [pk, column.name, column.sql_type,
-                column.sql_type_metadata.type, column.sql_type_metadata.limit || '',
-                column.sql_type_metadata.precision || '', column.sql_type_metadata.scale || '', column.default || '',
-                column.null, column.comment || '']
-        end
-        t
-      end
-    end
-
-    Pry.commands.block_command 'vd' do |name|
-      table_name = VD::get_table_name(name)
-      VD::table_info_vd(table_name)
-    end
-  end
-end

data/lib/arql/connection.rb

@@ -1,16 +0,0 @@
-module Arql
-  class Connection
-    class << self
-      def open(options)
-        print "Establishing DB connection to #{options[:host]}:#{options[:port]}"
-        ActiveRecord::Base.establish_connection(options)
-        print "\u001b[2K"
-        puts "\rDB connection to #{options[:host]}:#{options[:port]} established\n"
-        $C = ActiveRecord::Base.connection
-        $C.define_singleton_method(:dump) do |filename, no_create_db=false|
-          Arql::Mysqldump.new.dump_database(filename, no_create_db)
-        end
-      end
-    end
-  end
-end