arql 0.3.29 → 0.3.31

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

@@ -0,0 +1,55 @@
+* 自动记录 SQL 日志和 REPL 输入历史
+
+  如果希望 Arql 可以自动记录 SQL 日志和 REPL 输入历史，可以:
+
+  创建目录 =~/.arql.d/logs=
+  
+  创建一个文件 =~/.arql.d/sql_log.rb= ，内容如下：
+
+  #+BEGIN_SRC ruby
+    unless Arql::App.config[:append_sql]
+      log_root_dir = File.expand_path('~/.arql.d/logs')
+      log_dir = "#{log_root_dir}/%s" % Arql::App.env
+      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
+    
+      lfile = File.new(log_file, 'a')
+      lfile.sync = true
+      InputLogger = Logger.new(lfile)
+    
+      module Readline
+        class << self
+          alias_method :original_readline, :readline
+          def readline(*args)
+            Readline.original_readline(*args).tap do |user_input|
+              InputLogger.info(user_input)
+            end
+          end
+        end
+      end
+    end
+  #+END_SRC
+
+
+   然后在 =~/.arql.d/init.rb= 中引入这个文件:
+
+   #+BEGIN_SRC ruby
+     load(File.absolute_path(File.dirname(__FILE__) + "/sql_log.rb"))
+   #+END_SRC
+
+   这样就可以在 =~/.arql.d/logs= 目录下看到 SQL 日志和 REPL 输入历史了。
+
+   示例：
+
+   #+BEGIN_EXAMPLE
+     I, [2024-04-07T17:12:00.530341 #20440]  INFO -- : P.count
+     D, [2024-04-07T17:12:00.577305 #20440] DEBUG -- :   Post Count (22.6ms)  SELECT COUNT(*) FROM `post`
+     I, [2024-04-07T17:12:02.879312 #20440]  INFO -- : P.all.t
+     D, [2024-04-07T17:12:02.960014 #20440] DEBUG -- :   Post Load (64.1ms)  SELECT `post`.* FROM `post`
+     I, [2024-04-07T17:12:54.721861 #20440]  INFO -- : P.pluck(:gender)
+     D, [2024-04-07T17:12:54.756435 #20440] DEBUG -- :   Post Pluck (28.0ms)  SELECT `post`.`gender` FROM `post`
+   #+END_EXAMPLE
+
+

data/sql-log.org

@@ -0,0 +1,55 @@
+* Save SQL logs and REPL history automatically
+
+  If you want Arql to automatically save SQL logs and REPL history, you can:
+
+  Create a directory =~/.arql.d/logs=
+
+  Create a file =~/.arql.d/sql_log.rb= with the following content:
+
+  #+BEGIN_SRC ruby
+    unless Arql::App.config[:append_sql]
+      log_root_dir = File.expand_path('~/.arql.d/logs')
+      log_dir = "#{log_root_dir}/%s" % Arql::App.env
+      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
+    
+      lfile = File.new(log_file, 'a')
+      lfile.sync = true
+      InputLogger = Logger.new(lfile)
+    
+      module Readline
+        class << self
+          alias_method :original_readline, :readline
+          def readline(*args)
+            Readline.original_readline(*args).tap do |user_input|
+              InputLogger.info(user_input)
+            end
+          end
+        end
+      end
+    end
+  #+END_SRC
+
+  Then include this file in =~/.arql.d/init.rb=:
+
+  #+BEGIN_SRC ruby
+    load(File.absolute_path(File.dirname(__FILE__) + "/sql_log.rb"))
+  #+END_SRC
+
+  This way you can see SQL logs and REPL history in the =~/.arql.d/logs= directory.
+
+  Example:
+
+  #+BEGIN_EXAMPLE
+    I, [2024-04-07T17:12:00.530341 #20440]  INFO -- : P.count
+    D, [2024-04-07T17:12:00.577305 #20440] DEBUG -- :   Post Count (22.6ms)  SELECT COUNT(*) FROM `post`
+    I, [2024-04-07T17:12:02.879312 #20440]  INFO -- : P.all.t
+    D, [2024-04-07T17:12:02.960014 #20440] DEBUG -- :   Post Load (64.1ms)  SELECT `post`.* FROM `post`
+    I, [2024-04-07T17:12:54.721861 #20440]  INFO -- : P.pluck
+    D, [2024-04-07T17:12:54.756435 #20440] DEBUG -- :   Post Pluck (28.0ms)  SELECT `post`.`gender` FROM `post`
+  #+END_EXAMPLE
+
+  
+  

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: arql
 version: !ruby/object:Gem::Version
-  version: 0.3.29
+  version: 0.3.31
 platform: ruby
 authors:
 - Liu Xiang
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-13 00:00:00.000000000 Z
+date: 2024-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mysql2
@@ -304,13 +304,26 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
-- README.md
+- README-zh_CN.org
+- README.org
 - Rakefile
 - arql.gemspec
+- auto-set-id-before-save-zh_CN.org
+- auto-set-id-before-save.org
 - bin/console
 - bin/setup
+- custom-configurations-zh_CN.org
+- custom-configurations.org
+- define-associations-zh_CN.org
+- define-associations.org
 - exe/arql
 - exe/arql_setsid_wrapper
+- fuzzy-field-query-zh_CN.org
+- fuzzy-field-query.org
+- helper-for-datetime-range-query-zh_CN.org
+- helper-for-datetime-range-query.org
+- initializer-structure-zh_CN.org
+- initializer-structure.org
 - lib/arql.rb
 - lib/arql/app.rb
 - lib/arql/cli.rb
@@ -345,6 +358,13 @@ files:
 - lib/arql/ssh_proxy_patch.rb
 - lib/arql/vd.rb
 - 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
 licenses:
 - MIT