CsvMapper 技术文档

1. 安装指南

安装环境要求

• Ruby 1.8 及以上版本（包括 Ruby 1.9+）
• 在 Ruby 1.9 之前的版本中，需要安装 FasterCSV 库。

安装步骤

1. 打开终端或命令行工具。
2. 输入以下命令安装 csv-mapper 库：

   sudo gem install csv-mapper
   

3. 等待安装完成，确保安装成功。

2. 项目使用说明

基本使用

CsvMapper 是一个用于简化将 CSV 文件导入到 Ruby 中并转换为可用格式的库。以下是基本的使用示例：

示例 CSV 文件结构

First Name,Last Name,Age
John,Doe,27
Jane,Doe,26
Bat,Man,52
...etc...

简单使用示例

results = CsvMapper.import('/path/to/file.csv') do
  start_at_row 1
  [first_name, last_name, age]
end

results.first.first_name  # 输出: John
results.first.last_name   # 输出: Doe
results.first.age         # 输出: 27

自动属性发现示例

results = CsvMapper.import('/path/to/file.csv') do
  read_attributes_from_file
end

results.first.first_name  # 输出: John
results.first.last_name   # 输出: Doe
results.first.age         # 输出: 27

导入到 ActiveRecord 示例

虽然 CsvMapper 不依赖于 ActiveRecord，但可以轻松地将 CSV 文件导入到 ActiveRecord 模型中并保存。

# 定义一个 ActiveRecord 模型
class Person < ActiveRecord::Base; end

results = CsvMapper.import('/path/to/file.csv') do
  map_to Person # 映射到 Person ActiveRecord 类
  after_row lambda{|row, person| person.save }  # 解析每一行后保存记录
  
  start_at_row 1
  [first_name, last_name, age]
end

3. 项目 API 使用文档

CsvMapper.import(file_path)

• 功能: 导入 CSV 文件并将其转换为可用的数据结构。
• 参数:
  • file_path: CSV 文件的路径。
• 返回值: 包含 CSV 数据的数组。

start_at_row(row_number)

• 功能: 指定从哪一行开始读取数据。
• 参数:
  • row_number: 起始行号。

read_attributes_from_file

• 功能: 自动从 CSV 文件的标题行中读取属性。

map_to(class)

• 功能: 将解析后的数据映射到指定的类。
• 参数:
  • class: 目标类（如 ActiveRecord 模型）。

after_row(lambda)

• 功能: 在解析每一行后执行指定的操作。
• 参数:
  • lambda: 一个 lambda 函数，接收两个参数：当前行数据和映射后的对象。

4. 项目安装方式

使用 Gem 安装

sudo gem install csv-mapper

手动安装

1. 从 GitHub 或其他源下载 csv-mapper 的源代码。
2. 解压文件并进入项目目录。
3. 运行以下命令进行安装：

   gem build csv-mapper.gemspec
   sudo gem install csv-mapper-<version>.gem
   

通过以上步骤，您可以成功安装并使用 CsvMapper 库来处理 CSV 文件。