查看源代码 mix format (Mix v1.16.2)
格式化给定的文件和模式。
$ mix format mix.exs "lib/**/*.{ex,exs}" "test/**/*.{ex,exs}"
如果任何文件是 -
,那么输入将从 stdin 读取,输出将写入 stdout。
格式化选项
格式化程序将在当前目录中读取 .formatter.exs
文件以进行格式化程序配置。评估此文件应返回一个关键字列表。
以下是一个 .formatter.exs
文件的示例,它可以作为起点
[
inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
]
除了 Code.format_string!/2
中列出的选项之外,.formatter.exs
文件还支持以下选项
:inputs
(路径和模式列表) - 指定此任务要使用的默认输入。例如,["mix.exs", "{config,lib,test}/**/*.{ex,exs}"]
。模式将使用Path.wildcard/2
展开。:plugins
(模块列表) (自 v1.13.0 起) - 指定模块列表以自定义格式化程序的工作方式。有关更多信息,请参见下面的“插件”部分。:subdirectories
(路径和模式列表) - 指定具有自己的格式化规则的子目录。每个子目录都应该有一个.formatter.exs
,用于配置如何格式化该子目录中的条目。.formatter.exs
之间的配置不会共享或继承。如果一个.formatter.exs
将“lib/app”列为子目录,则.formatter.exs
中的规则将不可用在lib/app/.formatter.exs
中。请注意,父.formatter.exs
不得在其:inputs
配置中指定“lib/app”子目录内的文件。如果发生这种情况,哪个格式化程序配置将被选取的行为是不确定的。:import_deps
(作为原子的依赖项列表) - 指定将导入其格式化程序配置的依赖项列表。有关更多信息,请参见下面的“导入依赖项配置”部分。:export
(关键字列表) - 指定要导出的格式化程序配置。有关更多信息,请参见下面的“导入依赖项配置”部分。
特定于任务的选项
--check-formatted
- 检查文件是否已格式化。这在预提交钩子和 CI 脚本中很有用,如果你想拒绝带有未格式化代码的贡献。如果检查失败,格式化的内容不会写入磁盘。请记住,格式化的输出可能会在 Elixir 版本之间有所不同,因为改进和修复会应用于格式化程序。--no-exit
- 仅在与--check-formatted
一起使用时有效。如果你不希望此 Mix 任务失败(并返回一个非零退出代码),但仍然希望检查格式错误并将其打印到控制台,则传递此选项。--dry-run
- 格式化后不会保存文件。--dot-formatter
- 带有格式化程序配置的文件的路径。如果可用,则默认为.formatter.exs
。有关更多信息,请参见上面的“格式化选项”部分。--stdin-filename
- stdin 上正在格式化的文件的路径。如果你使用插件来支持自定义文件类型,例如.heex
,这将很有用。如果不传递此标志,则假定通过 stdin 传递的代码是有效的 Elixir 代码。默认为“stdin.exs”。
何时格式化代码
我们建议开发人员直接在他们的编辑器中格式化代码,无论是自动保存文件还是通过显式命令或键盘绑定。如果你的选择编辑器中没有此选项,添加所需的集成通常是调用以下命令的问题
$ cd $project && mix format $file
其中 $file
指的是当前文件,$project
是你项目的根目录。
还可以通过将模式和文件的列表传递给 mix format
来格式化整个项目中的代码,如本任务文档顶部所示。此列表也可以在 .formatter.exs
文件中的 :inputs
键下设置。
插件
可以自定义格式化程序的行为方式。插件必须实现 Mix.Tasks.Format
行为。例如,假设你的项目以两种不同的方式使用 Markdown:通过自定义 ~M
sigil 和通过具有 .md
和 .markdown
扩展名的文件。自定义插件将如下所示
defmodule MixMarkdownFormatter do
@behaviour Mix.Tasks.Format
def features(_opts) do
[sigils: [:M], extensions: [".md", ".markdown"]]
end
def format(contents, opts) do
# logic that formats markdown
end
end
传递给 format/2
的 opts
包含所有格式化选项,并且是以下之一
:sigil
(原子) - 正在格式化的 sigil,例如:M
。:modifiers
(字符列表) - sigil 修饰符列表。:extension
(字符串) - 正在格式化的文件的扩展名,例如".md"
。
现在,任何应用程序都可以按如下方式使用你的格式化程序
# .formatter.exs
[
# Define the desired plugins
plugins: [MixMarkdownFormatter, AnotherMarkdownFormatter],
# Remember to update the inputs list to include the new extensions
inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}", "posts/*.{md,markdown}"]
]
请注意,在使用插件运行格式化程序时,你的代码将首先被编译。
此外,输入插件的顺序就是格式化顺序。因此,在上面的 .formatter.exs
中,MixMarkdownFormatter
将在 AnotherMarkdownFormatter
之前格式化 markdown 文件和 sigil。
导入依赖项配置
此任务支持从依赖项导入格式化程序配置。
想要导出格式化程序配置的依赖项需要在项目的根目录中有一个 .formatter.exs
文件。在此文件中,依赖项可以列出一个 :export
选项,其中包含要导出的配置。目前,:export
下只支持一个选项::locals_without_parens
(其值与 Code.format_string!/2
中 :locals_without_parens
的值具有相同的形状)。
在依赖项的 :export
选项中列出的 :locals_without_parens
下的函数可以通过在项目的格式化程序配置文件的 :import_deps
选项中列出该依赖项来导入。
例如,假设你有一个名为 my_app
的项目,它依赖于另一个名为 my_dep
的项目。 my_dep
想要导出一些配置,所以 my_dep/.formatter.exs
将如下所示
# my_dep/.formatter.exs
[
# Regular formatter configuration for my_dep
# ...
export: [
locals_without_parens: [some_dsl_call: 2, some_dsl_call: 3]
]
]
为了导入配置,my_app
的 .formatter.exs
将如下所示
# my_app/.formatter.exs
[
import_deps: [:my_dep]
]