Sinatra – Configuration の邦訳

2010 年 9 月 14 日 by 山平

前から気になっていたSinatraを使ってみるに当たって、設定に関するドキュメントを邦訳してみました。

一応、英語は分かるけど技術者ではない知人に確認してもらっています。
意味は外していないとのことですが、鵜呑みにせずご自身で確認の上でご利用ください。

Configuring Settings
configuration設定

Sinatra includes a number of built-in settings that control whether certain features are enabled.
Settings are application-level variables that are modified using one of the set, enable, or disable methods and are available within the request context via the settings object.
Applications are free to set custom settings as well as the default, built-in settings provided by the framework.

Sinatraにはいくつかの組み込みの設定があり、これによって特定の機能を有効にするかどうかをコントロールします。
“設定”とはアプリケーションレベルの変数であり、設定オブジェクトを介することで各リクエストのコンテキスト内で利用したり、set、enable、disableいずれかのメソッドを使用したりして変更することができます。
アプリケーションは、Sinatraから提供される組み込みの設定値を使うこともできますし、自由に変更することもできます。

Using set, enable, and disable
set、enable、disableメソッドを使う

In its simplest form, the set method takes an setting name and value and creates an attribute on the application.
Settings can be accessed within requests via the settings object:

もっとも簡単な例ですが、setメソッドに名前と値を与えることで、アプリケーション属性を定義することができます。
定義した属性へは、リクエストの中で設定オブジェクトを介してアクセスします。

set :foo, 'bar'

get '/foo' do
"foo is set to " + settings.foo
end
Deferring evaluation
遅延評価

When the setting value is a Proc, evaluation is performed when the setting is read so that other settings may be used to calculate the value:

設定値がProcオブジェクトの場合、設定が読まれるときに評価が行われるため、評価を行う際に他の設定値を利用することもできます。
(訳注:このmayは推量ではなく許可)

set :foo, 'bar'
set :baz, Proc.new { "Hello " + foo }

get '/baz' do
"baz is set to " + settings.baz
end

The /baz response should come as “baz is set to Hello bar” unless the foo setting is modified.

fooの設定値が変更されていなければ、/bazへのアクセスに対するレスポンスは“baz is set to Hello bar”となるでしょう

Configuring multiple settings
多重設定

Multiple settings can be set by passing a Hash to set.
The previous example could be rewritten with:

ハッシュを通じて多重設定を行うことができます。
先ほどの例は以下のように書き換えることができます。

set :foo => 'bar', :baz => Proc.new { "Hello " + foo }
Setting multiple boolean settings with enable and disable
enableメソッドとdisableメソッドで複数のブール値を設定する

The enable and disable methods are sugar for setting a list of settings to true or false, respectively.
The following two code examples are equivalent:

enableメソッドとdisableメソッドは、TrueまたはFalseそれぞれの値をまとめて設定するためのシンタックスシュガーです。
次の2つの例は等価です。

enable  :sessions, :clean_trace
disable :logging, :dump_errors, :some_custom_option

setメソッドを使った場合

set :sessions, true
set :clean_trace, true
set :logging, false
set :dump_errors, false
set :some_custom_option, false

Built-in Settings
組み込みの設定項目

:environment – configuration/deployment environment
:environment – デプロイ環境の設定

A symbol specifying the deployment environment;
typically set to one of :development, :test, or :production.
The :environment defaults to the value of the RACK_ENV environment variable (ENV[‘RACK_ENV’]), or :development when no RACK_ENV environment variable is set.

The environment can be set explicitly:

デプロイ環境を指定するシンボル。
通常は、:development、:testまたは:productionのいずれかをsetします。
:environmentの初期値には、RACK_ENV(ENV[‘RACK_ENV’])で指定されている値が設定されます。
RACK_ENVが設定されていない場合は:developmentが初期値になります。
(訳注:sinatraは内部でRackを利用しているようです。)

デプロイ環境を明示的にsetする例

set :environment, :production
:sessions – enable/disable cookie based sessions
:sessions – cookieベースのセッションの有効化/無効化

Support for encrypted, cookie-based sessions are included with Sinatra but are disabled by default.
Enable them with:

Sinatraは標準で暗号化されたcookieベースのセッションをサポートしますが、デフォルトでは無効になっています。
セッションを有効化する例

set :sessions, true

Sessions are implemented by inserting the Rack::Session::Cookie component into the application’s middleware pipeline.

セッションは内部でRack::Session::Cookieコンポーネントを利用することで実装されています。

:logging – log requests to STDERR
:logging – STDERRへのログ出力を要求する

Writes a single line to STDERR in Apache common log format when enabled.
This setting is enabled by default in classic style apps and disabled by default in Sinatra::Base subclasses.

Internally, the Rack::CommonLogger component is used to generate log messages.

この設定が有効であれば、STDERRにApache共通ログ形式のログを出力します。
この設定の初期値は、クラシックスタイルのアプリでは有効化(訳注:設定値true)され、Sinatra::Baseのサブクラスでは無効化(訳注:設定値false)されます。
(訳注:“classic style apps”について)

内部的には、Rack::CommonLoggerコンポーネントを利用してログメッセージを生成しています。

:method_override – enable/disable the POST _method hack
:method_override – POSTメソッドのハックを有効化/無効化する

Boolean specifying whether the HTTP POST _method parameter hack should be enabled.
When true, the actual HTTP request method is overridden by the value of the _method parameter included in the POST body.
The _method hack is used to make POST requests look like other request methods (e.g., PUT, DELETE) and is typically only needed in shitty environments – like HTML form submission – that do not support the full range of HTTP methods.

The POST _method hack is implemented by inserting the Rack::MethodOverride component into the middleware pipeline.

HTTP POSTメソッドをハックするかどうかのブール値を設定します。
trueの場合、リクエストメソッドはPOSTリクエストで渡される_methodパラメータの値に上書きされます。

_methodパラメータによるメソッドのハックは、POSTリクエストを(例えばPUTやDELETEのような)他のリクエストメソッドのように見せかけるために使います。
これは通常、例えばHTTPメソッドの全範囲をサポートしないようなひどい環境の場合に限って必要とされます。

POSTメソッドのハックは内部でRack::MethodOverrideコンポーネントを利用することで実装されています。

:root – The application’s root directory
:root – アプリケーションのルートディレクトリ

The directory used as a base for the application.
By default, this is assumed to be the directory containing the main application file (:app_file setting).
The root directory is used to construct the default :public and :views settings.
A common idiom is to set the :root setting explicitly in the main application file as follows:

アプリケーションのベースとして使用するディレクトリを指定します。
デフォルト設定では、このディレクトリにアプリケーションのファイル(:app_file)も含まれています。
ルートディレクトリは設定項目:publicと:viewsのデフォルトパスを組み立てるために使用されます。
明示的にメインアプリケーションファイルのパスを:rootに設定する(ほぼ)定型的な記述の例

set :root, File.dirname(__FILE__)
:static – enable/disable static file routes
:static – 静的なファイルのルートの有効化/無効化

Boolean that determines whether static files should be served from the application’s public directory (see the :public setting).
When :static is truthy, Sinatra will check if a static file exists and serve it before checking for a matching route.

The :static setting is enabled by default when the public directory exists.

アプリケーションの公開ディレクトリで静的なファイルも提供するかどうかを決定するブール値です。
:staticの設定値がtrueの時、Sinatraはマッチするルートのチェックを行う前に、静的ファイルが存在していることをチェックします。
(訳注:truthyとは真偽値に変換すると真(True)になること)

公開ディレクトリが存在する場合、:staticはデフォルトで有効になります。

:public – static files directory
:public – 静的ファイルの格納ディレクトリ

A string specifying the directory where static files should be served from.
By default, this is assumed to be a directory named “public” within the root directory (see the :root setting).
You can set the public directory explicitly with:

静的ファイルを格納しているディレクトリパスを文字列で指定します。
デフォルト値は、ルートディレクトリ直下にある“public”という名前のディレクトリが存在すると仮定して設定されています(項:rootを参照してください)。
公開ディレクトリを明示的に設定する例

set :public, '/var/www'

The best way to specify an alternative directory name within the root of the application is to use a deferred value that references the :root setting:

公開ディレクトリとして、アプリケーションディレクトリ直下にデフォルト(public)とは異なる名前のディレクトリを指定したい場合、:rootの設定値を参照するとよいでしょう。

set :public, Proc.new { File.join(root, "static") }
:views – view template directory
:views – ビューテンプレートのディレクトリ

A string specifying the directory where view templates are located.
By default, this is assumed to be a directory named “views” within the application’s root directory (see the :root setting).
The best way to specify an alternative directory name within the root of the application is to use a deferred value that references the :root setting:

ビューテンプレートファイルを格納しているディレクトリパスを文字列で指定します。
デフォルト値は、ルートディレクトリ直下にある“views”という名前のディレクトリが存在すると仮定して設定されています(項:rootを参照してください)。
テンプレート格納ディレクトリとして、アプリケーションディレクトリ直下にデフォルト(views)とは異なる名前のディレクトリを指定したい場合、:rootの設定値を参照するとよいでしょう。

set :views, Proc.new { File.join(root, "templates") }
:run – enable/disable the built-in web server
:run – 組み込みのWebサーバの有効化/無効化

Boolean specifying whether the built-in web server is started after the app is fully loaded.
By default, this setting is enabled only when the :app_file matches $0.
i.e., when running a Sinatra app file directly with ruby myapp.rb.
To disable the built-in web server:

Webアプリケーションの読み込みが完了した後、組み込みのWebサーバを起動させるかどうかをブール値で指定します。
この設定のデフォルト値は、:app_fileが$0とマッチした場合にのみ有効に設定されます。
(訳注:$0は$PROGRAM_NAMEと同義)
すなわち、アプリケーションmyapp.rbを、Sinatraの:app_file上で実行する場合、組み込みWebサーバが起動します。
組み込みWebサーバを無効にする例

set :run, false
:server – handler used for built-in web server
:server – 組み込みWebサーバ呼び出しハンドラ

String or Array of Rack server handler names.
When the :run setting is enabled, Sinatra will run through the list and start a server with the first available handler.
The :server setting is set as follows by default:

文字列または配列でRackサーバのハンドラ名を指定します。
:runが有効に設定されている場合、Sinatraは与えられたハンドラのリストから、最初の利用可能な組み込みWebサーバを起動します。
:serverはデフォルトで以下のように設定されています。

set :server, %w[thin mongrel webrick]
:bind – server hostname or IP address
:bind – サーバのホスト名またはIPアドレス

String specifying the hostname or IP address of the interface to listen on when the :run setting is enabled.
The default value – ‘0.0.0.0’ – causes the server to listen on all available interfaces.
To listen on the loopback interface only, use

:runが有効に設定されている場合にリッスンするホスト名またはインターフェイスのIPアドレスを指定します。
デフォルト値’0.0.0.0’では、サーバは利用可能なすべてのインターフェイスでリッスンしようとします。
ループバックインターフェイスでのみリッスンする例

set :bind, 'localhost'
:port – server port
:port – サーバのポート番号

The port that should be used when starting the built-in web server when the :run setting is enabled.
The default port is 4567.
To set the port explicitly:

:runが有効の時、組み込みWebサーバ起動時に使用されるポート番号です。
デフォルトのポート番号は4567です。
明示的なポート設定の例

set :port, 9494
:app_file – main application file
:app_file – メインアプリケーションファイル

The :app_file setting is used to calculate the default :root, :public, and :views setting values.
A common idiom is to override the default detection heuristic by setting the :app_file explicitly from within the main application file:

:app_fileの設定は:root、:publicおよび:viewsのデフォルト値の算出に使用されます。
メインアプリケーション内で明示的に設定された:app_fileによってデフォルトの(:root、:publicおよび:viewsの)自動検知を上書きする(ほぼ)定型的な記述の例

set :app_file, __FILE__

It’s also used to detect whether Sinatra should boot a web server when using classic-style applications.

これはまた、クラッシックスタイルのアプリケーションを動作する場合に、Sinatraが組み込みWebサーバを起動するかどうかの決定に使われます。

:dump_errors – log exception backtraces to STDERR
:dump_errors – 例外発生時のバックトレースログをSTDERRに出力する

Boolean specifying whether backtraces are written to STDERR when an exception is raised from a route or filter.
This setting is enabled by default in classic style apps.
Disable with

ルートかフィルタで発生した例外のバックトレースをSTDERRに出力するかどうかのブール値を設定します。
(訳注:ルートとフィルタとは?)
クラッシックスタイルのアプリケーションの場合、デフォルトで有効です。
無効にする例

set :dump_errors, false
:clean_trace – scrub library entries from backtraces
:clean_trace – バックトレース中のライブラリのエントリーを取り除く

When the :clean_trace setting is enabled, library/framework entries are removed from exception backtraces before being written to STDERR (see :dump_errors setting) or being displayed on the development mode error page.

The :clean_trace setting is enabled by default in all environments.

:clean_traceが有効に設定されている場合、STDERRに出力される前もしくは開発モードのエラーページに表示される前に例外のバックトレースログ(:dump_errors参照)からライブラリおよびフレームワークのエントリを削除します。

すべての環境で:clean_traceはデフォルトで有効です。
Disable it to get full exception backtraces:
この設定を無効にしてすべての例外のバックトレースログを出力させる例

set :clean_trace, false
:raise_errors – allow exceptions to propagate outside of the app
:raise_errors – アプリケーション外に例外が伝播するのを許可する

Boolean specifying whether exceptions raised from routes and filters should escape the application.
When disabled, exceptions are rescued and mapped to error handlers which typically set a 5xx status code and render a custom error page.
Enabling the :raise_errors setting causes exceptions to be raised outside of the application where it may be handled by the server handler or Rack middleware, such as Rack::ShowExceptions or Rack::MailExceptions.

ルートとフィルタで発生した例外をアプリケーションでエスケープするかどうかのブール値を指定します。
無効にすると例外はrescureされて典型的な5xx系のステータスコードでエラーハンドラにマッピングされ、カスタムエラーページを応答します。
:raise_errorsを有効にすると、発生した例外はアプリケーション外部に伝播し、サーバのハンドラかRack(Rack::ShowExceptionsRack::MailExceptions)ミドルウェアがエラー処理するでしょう。

:lock – ensure single request concurrency with a mutex lock
:lock – mutex lockによって同時発生した各リクエストの単一性を保証する

Sinatra can be used in threaded environments where more than a single request is processed at a time.
However, not all applications and libraries are thread-safe and may cause intermittent errors or general weirdness.
Enabling the :lock setting causes all requests to synchronize on a mutex lock, ensuring that only a single request is processed at a time.

The :lock setting is disabled by default.

Sinatraはスレッド環境で利用することで、単一のリクエストを処理する時間でより多くのリクエストを処理することができます。
しかしながら、アプリケーションとライブラリのすべてがスレッドセーフではないことから時々エラーが発生したり、不可思議な事象が発生することがあるでしょう。
:lockを有効にすることで、すべてのリクエストをmutex lockによって同期させることができます。
これによって各リクエストが順次処理されることを保証します。

:lockはデフォルトで無効に設定されています。

:show_exceptions – enable classy error pages
:show_exceptions – 洒落たエラーページを出力する

Enable error pages that show backtrace and environment information when an unhandled exception occurs.
Enabled in development environments by default.

ハンドリングされない例外が発生した際にバックトレースログや環境情報を表示するエラーページを有効にします。
開発環境の場合、デフォルトで有効です。

タグ: , ,

TrackBack