Barista 技术文档

Barista 是一组工具，旨在让在 Rails 3、Rails 2 和 Rack 应用程序中使用 CoffeeScript 变得更加容易。您可以将其视为类似于 Compass，但它用于 CoffeeScript 而不是 Sass。

以下是对 Barista 项目的详细技术文档，包括安装指南、使用说明和 API 使用文档。

1. 安装指南

Rails 3

在 Rails 3 应用程序中添加 Barista 非常简单，只需在 Gemfile 中添加两个 gem，并运行两个命令。首先，打开您的 Gemfile 并添加以下内容：

gem "json" # 仅在 Ruby 1.8 或没有内置 JSON 支持的平台上需要
gem "barista"

然后，运行以下命令：

bundle install
rails g barista:install

这将安装 gem 并在 config/initializers/barista_config.rb 中生成一个文件，其中包含用于配置 Barista 选项的设置。

将您的 CoffeeScript 文件放在 app/coffeescripts 目录下，Barista 将在更改时自动编译它们到 public/javascripts。

Rails 2

Barista 同样支持深入集成到 Rails 2。唯一缺少的功能（目前 Rails 3 版本支持）是生成配置文件的内置支持。如果您在应用程序中使用 bundler，只需在 Gemfile 中添加以下内容：

gem "json" # 仅在 Ruby 1.8 或没有内置 JSON 支持的平台上需要
gem "barista"

如果您没有使用 bundler，执行 gem install json barista 并在应用程序中 require Barista 也应该足够让您开始使用。

Sinatra

将 Barista 添加到 Sinatra 应用程序中相对简单。与 Rails 2 和 Rails 3 类似，您首先需要添加并 require Barista gem 和（可选的）json gem。然后，在应用程序的作用域中注册 Barista 扩展：

register Barista::Integration::Sinatra

这会自动设置 Barista 环境和其他详细信息（例如自动编译过滤器）。

其他 Rack-based 框架

尽管 Barista 是为支持 Rails 和 Sinatra 而构建的，但它也可以与任何 Rack-based 框架一起使用。对于正确的集成，需要在声明 middleware 的位置注册 Barista 使用的两个 middleware。Barista::Filter 仅在 Barista 执行编译时注册，而 Barista::Server::Proxy 应在需要自动服务 coffeescript.js 文件时注册。

例如，您的 config.ru 可能如下所示：

# 设置代码...
use Barista::Filter if Barista.add_filter?
use Barista::Server::Proxy
run MyRackApplication

在上述代码运行之前，您需要在任何位置配置 Barista，例如：

# Barista (用于 CoffeeScript 支持)
Barista.app_root = root
Barista.root     = File.join(root, 'coffeescripts')
Barista.setup_defaults
barista_config = root + '/barista_config.rb'
require barista_config if File.exist?(barista_config)

2. 使用说明

将 CoffeeScript 文件放在指定的目录（Rails 3 为 app/coffeescripts）后，Barista 将在文件更改时自动编译它们到 JavaScript。在开发和测试模式下，Barista 会嵌入 CoffeeScript，而不是预编译。

要强制编译所有 JavaScript，可以运行：

rake barista:brew

3. 项目 API 使用文档

Barista 提供了多种配置选项，您可以在 config/initializers/barista_config.rb 中设置它们。以下是一些主要的配置选项：

• verbose: 输出调试错误消息。
• bare: 不将编译的 JS 包裹在闭包中。
• add_filter: 自动添加一个处理更改的 around 过滤器。
• add_preamble: 向编译的 JS 中添加时间 + 路径前缀。
• exception_on_error: 在编译错误时抛出异常。
• embedded_interpreter: 对于 include 标签和 Haml 过滤器，嵌入 CoffeeScript 和链接到 Coffee 文件，而不是编译。

更多配置选项和详细信息，请参考项目的 GitHub 仓库和 Wiki。

4. 项目安装方式

Barista 的安装方式取决于您使用的是 Rails 3、Rails 2 还是 Sinatra。以下是一般步骤：

• 对于 Rails 3 和 Rails 2，将 Barista 和 json gem 添加到 Gemfile 中，然后运行 bundle install 和 rails g barista:install。
• 对于 Sinatra，将 Barista gem require 到您的应用程序中，并在应用程序的作用域中注册 Barista::Integration::Sinatra。
• 对于其他 Rack-based 框架，您需要手动设置 Barista 配置并注册相应的 middleware。

确保在 Gemfile 中添加 Barista 的依赖，然后运行 bundle install 来安装所有必要的 gem。