配置文件

在 PySpigot 中，脚本可以加载、访问和保存配置文件。所有脚本使用配置管理器访问的配置文件都会自动存储在 PySpigot 插件文件夹内的config文件夹中。

有关将配置管理器导入到您的脚本中的说明，请访问常规信息页面。

信息

这并非与配置文件操作相关的详尽指南。有关可用方法/函数的更完整文档，请参阅JavaDocs。此处列出的所有方法都可以从您的脚本中调用。

配置管理器的使用

以下功能可从配置管理器中使用：

• doesConfigExist(filePath): 此函数检查给定名称或路径下是否存在配置文件。如果文件存在，则返回True，否则返回False。
• loadConfig(filePath): 此函数加载配置文件，如果文件不存在将自动创建。需指定要加载和/或创建的文件名或路径。返回表示加载/创建的配置的ScriptConfig对象。未指定默认值。
• loadConfig(filePath, defaults): 此函数加载配置文件，如果文件不存在将自动创建。需指定要加载和/或创建的文件名或路径。返回表示加载/创建的配置的ScriptConfig对象。还接受用于指定配置所需默认值的 YAML 格式字符串(defaults)。
• reloadConfig(config): 此函数重新加载配置，以加载文件中的任何更改。需要重新加载的配置（一个ScriptConfig对象）。返回另一个表示重新加载的配置的ScriptConfig对象。
  • 提示: reloadConfig 函数将在未来的 PySpigot 版本中移除。请改用 ScriptConfig 中的reload函数（下文更详细介绍）。
• deleteConfig(filePath): 此函数将删除指定名称或路径的配置文件。如果成功删除文件，则返回True，如果之前未在提供的名称或路径下存在任何文件则返回False。
• getConfigFolder(): 此函数返回一个路径（位于 PySpigot 插件文件夹内），指向配置文件所在的文件夹。

Tip

ConfigManager 允许在处理脚本配置文件时使用子文件夹进行组织。只需将配置文件作为路径传递给接受filePath参数的上述方法即可。例如，ps.config_manager.loadConfig('test_script/config.yml') 将加载configs文件夹中test_script子文件夹内的config.yml文件。

ScriptConfig 使用

加载/重新加载配置将返回一个 ScriptConfig 对象。该对象具有许多可用的方法/函数：

• 有多种函数可用于从配置文件中获取数据。要查看可以用来从配置文件中检索数据的方法/函数的完整列表，请参阅 Spigot JavaDocs
• set(key, value): 在给定的键处设置配置文件中的值。接受表示要写入的键的键和要写入的值。
• setIfNotExists(path, value): 在给定路径处设置配置文件中的值，仅在该路径处尚未设置值时。如果将路径设置为该值（路径以前未设置），则返回True，或者如果将路径未设置为给定值（路径以前已设置），则返回False。如果要向配置文件中添加新键但不希望覆盖已设置的键，则此功能很有用。
• getConfigFile(): 获取对应于配置文件的文件。
• getConfigPath(): 获取对应于配置的文件的路径。
• load(): 加载配置文件。在正常情况下，不应调用此函数，因为在从 ScriptManager 调用loadConfig时已执行该操作。
• reload(): 重新加载来自文件的配置。如果自上次加载/重新加载以来对文件进行了更改，则此函数很有用，因为这些更改在重新加载配置之前不会自动反映。
• save(): 保存配置，以便您设置的任何值都将持久保存。保存后会自动重新加载配置。

警告

对配置的更改不会自动保存到文件中！您必须调用save来将更改写入配置文件。

默认配置

Bukkit配置库（PySpigot配置系统所构建的基础）内置了处理默认配置数值的系统。默认值是在加载配置时可以指定的数值，在配置文件中未定义数值时，配置系统将使用这些默认值备用。这些默认值仅在配置文件中路径/键不存在时才会被使用。接下来以以下示例为例：

配置文件：

key-1: 'Key 1 is set'
key-2: 'Key 2 is set'

脚本：

import pyspigot as ps

config_defaults = """
key-1: 'Key 1'
key-2: 'Key 2'
key-3: 'Key 3'
""" #(1)!

config = ps.config.loadConfig('script_config.yml', config_defaults) #(2)!

print(config.getString('key-1')) #(3)!
print(config.getString('key-2')) #(4)!
print(config.getString('key-3')) #(5)!

1. 在这里，我们以YAML格式定义了一个包含配置文件所需默认值的多行字符串。

2. 在这里，加载了配置文件，传入了配置文件名script_config.yml以及我们之前定义的config_defaults。

3. 在这里，我们打印了配置文件中key-1的值。

4. 在这里，我们打印了配置文件中key-2的值。

5. 在这里，我们打印了配置文件中key-3的值。

控制台输出：

[14:17:22 INFO]: [PySpigot/test.py] [STDOUT] Key 1 is set
[14:17:22 INFO]: [PySpigot/test.py] [STDOUT] Key 2 is set
[14:17:22 INFO]: [PySpigot/test.py] [STDOUT] Key 3

如上面的代码的控制台输出所示，key-1 和 key-2 分别打印出"Key 1 is set" 和 "Key 2 is set"，因为这两个在配置文件中实际上有定义。然而，由于key-3 在配置文件中并未定义，它会默认为key-3 的默认值，该值在config_defaults 字符串中先前指定为"Key 3"。

指定默认值特别有用，如果您想要向现有配置文件添加新的配置值，但又不想删除和重新生成整个配置。如果用户意外删除了配置值，但是您不希望脚本因找不到配置值而出错（因为它将回退到您指定的默认值），这也很有用。

另一种指定默认值的方式

Bukkit 配置系统还内置了允许您在获取值时指定默认值的函数。例如：

import pyspigot as ps

config = ps.config.loadConfig('script_config.yml') # (1)!

print(config.getString('key-1', 'Key 1 default')) # (2)!
print(config.getString('key-2', 'Key 2 default')) # (3)!
print(config.getString('key-3', 'Key 3 default')) # (4)!

1. 在这里，加载配置文件时传入配置文件的名称script_config.yml。请注意，这与前面的示例不同，因为没有指定config_defaults。

2. 在这里，我们获得配置文件中与key-1相关的值。我们还传递了默认值"Key 1 default"，如果配置文件中未定义key-1，则会返回该默认值。

3. 在这里，我们获得配置文件中与key-2相关的值。我们还传递了默认值"Key 2 default"，如果配置文件中未定义key-2，则会返回该默认值。

4. 在这里，我们从配置文件中获取与 key-3 关联的值。我们还传递了一个默认值 "Key 3 default"，如果在配置文件中未定义 key-3，则会返回这个默认值。

在上述代码中，默认值是在 getString 函数中传递的，仅在配置中不存在该值时才会返回。获取其他类型数值时也有类似的函数，包括 getInt、getDouble、getLong、getBoolean 等。

特殊的 Python 数据类型

列表、集合和元组

列表、集合和元组在 yaml 语法中都保存为列表的形式，看起来像这样：

list:
  - 'item1'
  - 'item2'
  - 'item3'

字典

字典在 yaml 语法中以 key: value 的格式表示。例如，考虑以下代码：

thisdict = {
  "brand": "Ford",
  "model": "Mustang",
  "year": 1964
}

script_config.set('dict', thisdict)

这将以以下格式输出到 yaml 语法：

dict:
  year: 1964
  model: Mustang
  brand: Ford

当然，您也可以在字典中嵌套列表、集合、元组和其他字典，并且它们将被相应地保存。字典特别适用于一次设置多个配置值，而无需逐个设置每个值。

代码示例

让我们来看下面的代码，它加载一个配置，从中读取一个数字和一个字符串，然后写入，最后保存。

import pyspigot as ps # (1)!

script_config = ps.config.loadConfig('test.yml') # (2)!

a_number = script_config.getInt('test-number') # (3)!
a_string = script_config.getString('test-string') # (4)!

script_config.set('test-set', 1337) # (5)!
script_config.save() # (6)!

1. 在这里，我们将PySpigot导入为ps，以便利用配置管理器(config)。

2. 在这里，我们使用配置管理器加载配置。幸运的是，配置管理器可以轻松从pyspigot辅助模块中以变量名config的方式访问。loadConfig函数接受一个表示要加载的配置文件名称的字符串。如果该文件不存在，它将自动创建。

3. 在这里，我们从配置文件中的键test-number下读取一个数值(int)，并将该值赋给a_number。

4. 在这里，我们从配置文件中的键test-string下读取一个字符串(str)，并将该值赋给a_string。

5. 在这里，我们将数值1337设置为配置键test-set的值。

6. 最后，我们使用save()函数保存配置。这样可以确保通过set方法对配置文件做出的任何更改都会保存在配置文件中。

注意

配置文件对于每个脚本并非唯一！任何脚本都可以访问任何配置文件。请使用唯一的名称。

摘要

• 脚本可以加载和保存到配置文件，这些文件会自动存储在PySpigot插件文件夹的configs文件夹中。
• 要加载配置，请使用config.load(filePath)。filePath参数是您希望加载的配置文件的名称或路径（包括.yml扩展名）。如果配置文件不存在，将自动为您创建。这将返回一个ScriptConfig对象，用于访问配置的内容并写入配置。
• 若要从加载的配置中获取值的所有可用函数/方法，请参阅Javadocs。
• 要在配置中设置值，请使用script_config.set(key, value)，其中key是要写入的键，value是要写入的值。
• 您可以通过将包含默认配置值的YAML格式字符串传递给loadConfig函数来设置配置默认值。
• 最后，要保存配置，请使用script_config.save()。