文件监视器（Filewatcher）技术文档

本文档旨在提供详细的安装指南、使用说明和项目API使用文档，帮助用户深入了解并使用Filewatcher项目。

一、安装指南

安装Filewatcher非常简单，可以通过以下任一方式完成：

1. 使用gem直接安装：

gem install filewatcher

2. 使用Bundler进行安装：

在Gemfile文件中添加以下代码：

gem 'filewatcher'

然后执行以下命令：

bundle install

二、项目使用说明

Filewatcher是一个轻量级的文件监视工具，它通过轮询来监控文件系统的变化。以下是项目的基本使用方法：

监视文件和目录

require 'filewatcher'

Filewatcher.new(['lib/', 'Rakefile']).watch do |changes|
  changes.each do |filename, event|
    puts "#{filename} #{event}"
  end
end

监视单个目录

Filewatcher.new('lib/').watch do |changes|
  # ...
end

监视目录，不包括子目录

Filewatcher.new('lib/*').watch do |changes|
  # ...
end

监视绝对路径的目录

Filewatcher.new('/tmp/foo').watch do |changes|
  # ...
end

检测文件更新、添加或删除

Filewatcher.new(['README.rdoc']).watch do |changes|
  changes.each do |filename, event|
    puts "文件 #{event}: #{filename}"
  end
end

重命名文件的检测

Filewatcher.new(['lib/'], every: true).watch do |changes|
  changes.each do |filename, event|
    puts "文件 #{event}: #{filename}"
  end
end

使用插件

你可以为Filewatcher加载插件来扩展核心功能。例如：

require 'filewatcher'
require 'filewatcher-spinner'

Filewatcher.new('lib/', spinner: true).watch do |changes|
  changes.each do |filename, event|
    puts "#{filename} #{event}"
  end
end

三、项目API使用文档

以下是Filewatcher的一些API选项和使用示例：

排除特定文件

Filewatcher.new('**/*.*', exclude: '**/*.rb', interval: 0.1).watch do |changes|
  changes.each do |filename, event|
    puts filename
  end
end

使用模式匹配文件名

Filewatcher.new(['*.rb', '*.xml']).watch do |changes|
  changes.each do |filename, _event|
    puts "更新 #{filename}"
  end
end

控制监视状态

filewatcher = Filewatcher.new(['*.rb'])
thread = Thread.new(filewatcher) { |fw| fw.watch { |changes| p changes } }
# ...
filewatcher.pause       # 停止响应文件系统变化
filewatcher.finalize    # 确保暂停之前的所有文件系统变化得到处理
# ...
filewatcher.resume      # 重新开始响应，但不处理暂停期间的文件系统变化
# ...
filewatcher.stop        # 停止响应文件系统变化，并获取最终文件系统快照
thread.join

filewatcher.finalize    # 确保结束监视之前的所有文件系统变化得到处理

使用路径名

require 'pathname'

Filewatcher.new(['**/*.*']).watch do |changes|
  changes.each do |filename, event|
    path = Pathname.new(filename)
    puts "基本名         : #{path.basename}"
    puts "相对文件名    : #{File.join('.', path)}"
    puts "绝对文件名    : #{path.realpath}"
  end
end

通过以上内容，用户可以详细了解如何安装、使用以及利用Filewatcher的API进行开发。