檢視原始碼 EEx (EEx v1.16.2)

EEx 代表 Embedded Elixir。

Embedded Elixir 讓您能以穩健的方式將 Elixir 程式碼嵌入字串中。

iex> EEx.eval_string("foo <%= bar %>", bar: "baz")
"foo baz"

此模組提供三個主要 API 供您使用

  1. 直接評估字串 (eval_string/3) 或檔案 (eval_file/3)。這是最簡單的 API，但也是最慢的，因為程式碼是在執行階段評估，而不是預先編譯。

  2. 從字串 (function_from_string/5) 或檔案 (function_from_file/5) 定義函式。這讓您能將範本嵌入模組中的函式中，然後編譯。如果您在編譯階段有存取範本，這是首選的 API。

  3. 將字串 (compile_string/2) 或檔案 (compile_file/2) 編譯成 Elixir 語法樹。這是上述兩個函式使用的 API，如果您想提供自己的處理編譯範本的方式，也可以使用。

上述 API 支援多個選項，文件如下。您也可以傳遞自訂 EEx 程式碼編譯方式的引擎。

選項

除非另有註明，此模組中的所有函式都接受與 EEx 相關的選項。它們是

  • :file - 範本中要使用的檔案。預設為範本讀取的檔案，或從字串編譯時為 "nofile"。

  • :line - 用作範本開頭的行。預設為 1。

  • :indentation - (自 v1.11.0 起) 在每一新行後新增至欄位的整數。預設為 0。

  • :engine - 要用於編譯的 EEx 引擎。預設為 EEx.SmartEngine。

  • :trim - 如果為 true，會修剪引號左右兩側的空白，只要至少有一個換行符號存在。所有後續的換行符號和空白都會移除，但會保留一個換行符號。預設為 false。

  • :parser_options - (自 1.13.0 起) 允許自訂產生的已剖析程式碼。請參閱 Code.string_to_quoted/2 以了解可用的選項。請注意，如果傳入選項 :file、:line 和 :column，則會略過這些選項。預設為 Code.get_compiler_option(:parser_options) (如果未設定，則預設為 [])。

標籤

EEx 支援多個標籤，如下所述

<% Elixir expression: executes code but discards output %>
<%= Elixir expression: executes code and prints result %>
<%% EEx quotation: returns the contents inside the tag as is %>
<%!-- Comments: they are discarded from source --%>

EEx 支援其他標籤，某些引擎可能會使用這些標籤，但預設情況下這些標籤沒有意義

<%| ... %>
<%/ ... %>

引擎

EEx 有引擎的概念，允許您修改或轉換從給定字串或檔案中提取的程式碼。

預設情況下，EEx 使用 EEx.SmartEngine，它在簡單的 EEx.Engine 之上提供了一些便利性。

EEx.SmartEngine

智慧型引擎使用 EEx 預設規則，並新增 @ 建構用於讀取範本指派

iex> EEx.eval_string("<%= @foo %>", assigns: [foo: 1])
"1"

換句話說，<%= @foo %> 轉換為

<%= {:ok, v} = Access.fetch(assigns, :foo); v %>

當範本所需的變數數量在編譯時未指定時，assigns 延伸很有用。

摘要

類型

column()
line()
marker()
metadata()
token()

函式

compile_file(filename, options \\ [])

取得 filename 並產生 Elixir 可以評估或編譯為函式的引號表達式。

compile_string(source, options \\ [])

取得字串 source 並產生 Elixir 可以評估或編譯為函式的引號表達式。

eval_file(filename, bindings \\ [], options \\ [])

取得 filename 並使用 bindings 評估值。

eval_string(source, bindings \\ [], options \\ [])

取得字串 source 並使用 bindings 評估值。

function_from_file(kind, name, file, args \\ [], options \\ [])

從檔案內容產生函式定義。

function_from_string(kind, name, template, args \\ [], options \\ [])

從提供的字串產生函式定義。

tokenize(contents, opts \\ [])

根據提供的選項對提供的內容進行標記化。

類型

連結到此類型

column()

檢視原始碼 
@type column() :: non_neg_integer()
連結到此類型

line()

檢視原始碼 
@type line() :: non_neg_integer()
連結到此類型

marker()

檢視原始碼 
@type marker() :: ~c"=" | ~c"/" | ~c"|" | []
連結到此類型

metadata()

檢視原始碼 
@type metadata() :: %{column: column(), line: line()}
連結到此類型

token()

檢視原始碼 
@type token() ::
  {:comment, charlist(), metadata()}
  | {:text, charlist(), metadata()}
  | {:expr | :start_expr | :middle_expr | :end_expr, marker(), charlist(),
     metadata()}
  | {:eof, metadata()}

函式

連結到此函式

compile_file(filename, options \\ [])

檢視原始碼 
@spec compile_file(
  Path.t(),
  keyword()
) :: Macro.t()

取得 filename 並產生 Elixir 可以評估或編譯為函式的引號表達式。

如果您想將 EEx 範本編譯成程式碼並將該程式碼注入某處或在執行階段評估，這將很有用。

產生的引號程式碼將使用範本中定義的變數，這些變數將從評估程式碼的內容中取得。如果您有範本，例如 <%= a + b %>，則回傳的引號程式碼將在評估它的內容中使用 a 和 b 變數。請參閱以下範例。

支援的 options 在 模組文件 中描述。

範例 

# sample.eex
<%= a + b %>

# In code:
quoted = EEx.compile_file("sample.eex")
{result, _bindings} = Code.eval_quoted(quoted, a: 1, b: 2)
result
#=> "3"
連結到此函式

compile_string(source, options \\ [])

檢視原始碼 
@spec compile_string(
  String.t(),
  keyword()
) :: Macro.t()

取得字串 source 並產生 Elixir 可以評估或編譯為函式的引號表達式。

如果您想將 EEx 範本編譯成程式碼並將該程式碼注入某處或在執行階段評估，這將很有用。

產生的引號程式碼將使用範本中定義的變數，這些變數將從評估程式碼的內容中取得。如果您有範本，例如 <%= a + b %>，則回傳的引號程式碼將在評估它的內容中使用 a 和 b 變數。請參閱以下範例。

支援的 options 在 模組文件 中描述。

範例 

iex> quoted = EEx.compile_string("<%= a + b %>")
iex> {result, _bindings} = Code.eval_quoted(quoted, a: 1, b: 2)
iex> result
"3"
連結到此函式

eval_file(filename, bindings \\ [], options \\ [])

檢視原始碼 
@spec eval_file(Path.t(), keyword(), keyword()) :: String.t()

取得 filename 並使用 bindings 評估值。

支援的 options 在 模組文件 中描述。

範例 

# sample.eex
foo <%= bar %>

# IEx
EEx.eval_file("sample.eex", bar: "baz")
#=> "foo baz"
連結到此函式

eval_string(source, bindings \\ [], options \\ [])

檢視原始碼 
@spec eval_string(String.t(), keyword(), keyword()) :: String.t()

取得字串 source 並使用 bindings 評估值。

支援的 options 在 模組文件 中描述。

範例 

iex> EEx.eval_string("foo <%= bar %>", bar: "baz")
"foo baz"
連結到此巨集

function_from_file(kind, name, file, args \\ [], options \\ [])

檢視原始碼 (巨集)

從檔案內容產生函式定義。

第一個引數是產生的函式的類型（:def 或 :defp）。name 引數是產生的函式將擁有的名稱。file 是 EEx 範本檔案的路徑。args 是產生的函式將接受的引數清單。它們將在 EEx 範本內可用。

如果您有範本，但您想在模組內預先編譯以提高速度，則此函式很有用。

支援的 options 在 模組文件 中描述。

範例 

# sample.eex
<%= a + b %>

# sample.ex
defmodule Sample do
  require EEx
  EEx.function_from_file(:def, :sample, "sample.eex", [:a, :b])
end

# iex
Sample.sample(1, 2)
#=> "3"
連結到此巨集

function_from_string(kind, name, template, args \\ [], options \\ [])

檢視原始碼 (巨集)

從提供的字串產生函式定義。

第一個引數是產生的函式的類型（:def 或 :defp）。name 引數是產生的函式將擁有的名稱。template 是包含 EEx 範本的字串。args 是產生的函式將接受的引數清單。它們將在 EEx 範本內可用。

支援的 options 在 模組文件 中描述。

範例 

iex> defmodule Sample do
...>   require EEx
...>   EEx.function_from_string(:def, :sample, "<%= a + b %>", [:a, :b])
...> end
iex> Sample.sample(1, 2)
"3"
連結到此函式

tokenize(contents, opts \\ [])

檢視原始碼 (自 1.14.0 起) 
@spec tokenize([char()] | String.t(), opts :: keyword()) ::
  {:ok, [token()]} | {:error, String.t(), metadata()}

根據提供的選項對提供的內容進行標記化。

選項

  • :line - 開始行數的整數。預設為 1。
  • :column - 開始欄位的整數。預設為 1。
  • :indentation - 表示縮排的整數。預設為 0。
  • :trim - 告訴 token 處理器是否要修剪內容。預設為 false。
  • :file - 可以是檔案或字串 "nofile"。

範例 

iex> EEx.tokenize('foo', line: 1, column: 1)
{:ok, [{:text, 'foo', %{column: 1, line: 1}}, {:eof, %{column: 4, line: 1}}]}

結果

它會傳回 {:ok, [token]}，其中 token 為下列其中之一

  • {:text, content, %{column: column, line: line}}
  • {:expr, marker, content, %{column: column, line: line}}
  • {:start_expr, marker, content, %{column: column, line: line}}
  • {:middle_expr, marker, content, %{column: column, line: line}}
  • {:end_expr, marker, content, %{column: column, line: line}}
  • {:eof, %{column: column, line: line}}

或在發生錯誤時傳回 {:error, message, %{column: column, line: line}}。請注意，未來可能會新增新的 token。