查看“︁Module:Get/doc”︁的源代码

本模块灵感来源于JSONPath。

假设有这样一个数据：

<SyntaxHighLight lang="lua">
data = {
	store = {
		books = {
			{
				category = "reference",
				author = "Nigel Rees",
				title = "Sayings of the Century",
				price = 8.95
			},
			{
				category = "fiction",
				author = "Evelyn Waugh",
				title = "Sword of Honour",
				price = 12.99
			},
			{
				category = "fiction",
				author = "Herman Melville",
				title = "Moby Dick",
				isbn = "0-553-21311-3",
				price = 8.99
			},
			{
				category = "fiction",
				author = "J. R. R. Tolkien",
				title = "The Lord of the Rings",
				isbn = "0-395-19395-8",
				price = 22.99
			}
		},
		bicycle = {
			color = "red",
			price = 399
		}
	}
}
</SyntaxHighLight>

用法：

<SyntaxHighLight lang="lua">
> local get = require('Module:Get')

> -- 获取data.store.books的所有子项的author（JSONPath：$.store.books[*].author)
> get(data).store.books:items().author()
{"Nigel Rees", "Evelyn Waugh", "J. R. R. Tolkien", "J. R. R. Tolkien"}

> -- 获取data内任意深度的author（JSONPath：$..author）
> get(data)._.author()
{"Nigel Rees", "Evelyn Waugh", "J. R. R. Tolkien", "J. R. R. Tolkien"}

> -- 获取data.store内任意深度的price（JSONPath：$.store..price）
> get(data).store._.price()
{8.95, 12.99, 8.99, 22.99, 399}

> -- 获取data.store内任意深度的books的第3个子项（JSONPath：$..book[2]）
> get(data)._.books[3]()
{{ category = "fiction", author = "Herman Melville", title = "Moby Dick", isbn = "0-553-21311-3", price = 8.99 }}

> -- 获取data内任意深度的books的子项中满足price < 10的项目（JSONPath：$..books[?@.price<10]
> get(data)._.books[function (x) return x.price < 10 end]()
{
	{ category = "reference", author = "Nigel Rees", title = "Sayings of the Century", price = 8.95 },
	{ category = "fiction", author = "Herman Melville", title = "Moby Dick", isbn = "0-553-21311-3", price = 8.99 },
}
</SyntaxHighLight>

== <code>get(...)</code> ==
<code>get(...)</code>返回一个<code>Getter</code>对象，可以传多个值。

<SyntaxHighLight lang="lua">
> get(data)._.author()
{"Nigel Rees", "Evelyn Waugh", "J. R. R. Tolkien", "J. R. R. Tolkien"}

> get(data, { author = "Foo" }, { bar = { author = "Bar" } })._.author()
{"Nigel Rees", "Evelyn Waugh", "J. R. R. Tolkien", "J. R. R. Tolkien", "Foo", "Bar"}
</SyntaxHighLight>

特别地，对于get函数返回的<code>Getter</code>对象，它迭代时将依次返回每个非<code>nil</code>参数，因此你可以这样用<code>get</code>函数：

<SyntaxHighLight lang="lua">
for v in get('a', 'b', nil, 'd') do  -- 或 get('a', 'b', nil, 'd'):generate()
	print(i, v)
end
--[[ 输出：
a
b
d
]]
</SyntaxHighLight>

== 方法 ==
每个<code>Getter</code>对象都有以下方法：

=== 非链式调用方法 ===
==== <code>:all()</code> ====
返回一个包含查找到的值的列表。该列表具有<code>table</code>库的方法，以及一个字段<code>n</code>表示列表长度。

<SyntaxHighLight lang="lua">
> get(data).store.books:items().author:all()
> get(data).store.books:items().author()  -- 简写，建议仅在整个表达式写在一行时使用
{"Nigel Rees", "Evelyn Waugh", "J. R. R. Tolkien", "J. R. R. Tolkien"}

> get(data).store.books:items().author:all():concat(" & ")
Nigel Rees & Evelyn Waugh & J. R. R. Tolkien & J. R. R. Tolkien
</SyntaxHighLight>

==== <code>:one()</code> ====
返回结果中的第一个值，如果不存在则返回<code>nil</code>。

<SyntaxHighLight lang="lua">
> get(data).store.books:items().author:one()
"Nigel Rees"
</SyntaxHighLight>

==== <code>:must_one([message])</code> ====
返回结果中的第一个值，如果不存在则报错。

<SyntaxHighLight lang="lua">
> get(data).store.books:items().author:one()
"Nigel Rees"
</SyntaxHighLight>

==== <code>:unpack()</code> ====
解包，类似Lua标准库的<code>unpack</code>（在5.2及以上版本中为<code>table.unpack</code>）。

<SyntaxHighLight lang="lua">
> get(data).store.books:items().author:unpack()
"Nigel Rees", "Evelyn Waugh", "J. R. R. Tolkien", "J. R. R. Tolkien"
</SyntaxHighLight>

==== <code>:iterate()</code> ====
<code>[[#:all()|:all()]]</code>返回的是一个包含了所有结果的列表，而<code>:iterate()</code>的返回值能用于<code>for</code>循环。

<SyntaxHighLight lang="lua">
-- 第一个值必须忽略，即`_`，它存储了内部信息，使用者完全用不上这个值
for _, author in get(data).store.books:items().author:iterate() do print(author) end
-- `:iterate()` 可以省略且推荐省略，上下两行代码等价
for _, author in get(data).store.books:items().author do print(author) end
--[[ 输出：
Nigel Rees
Evelyn Waugh
J. R. R. Tolkien
J. R. R. Tolkien
]]
</SyntaxHighLight>

==== <code>:generate()</code> ====
返回一个迭代器函数，每次调用将得到下一个结果，直到所有结果都返回（该迭代器是有副作用的，即非纯函数的）。该方法与<code>:iterate()</code>类似，可用于<code>for</code>循环，区别是该方法返回的迭代器函数不会输出内部状态。

在且仅在<code>for</code>循环中，<code>:generate()</code>可以省略，更推荐省略，除非查询结果（注意是查询结果而不是待查数据）有非常多，多到影响性能。

<SyntaxHighLight lang="lua">
for author in get(data).store.books:items().author:generate() do print(author) end
for author in get(data).store.books:items().author do print(author) end  -- 省略:generate()
--[[ 输出：
Nigel Rees
Evelyn Waugh
J. R. R. Tolkien
J. R. R. Tolkien
]]
</SyntaxHighLight>

=== 链式调用方法 ===
链式调用方法将返回一个<code>Getter</code>对象。

==== <code>:field(key)</code> ====
获取字段的值，一般不需要用这个方法，直接<code>.xxx</code>即可。而当字段的键为<code>'_'</code>或函数时，只有调用此方法才能获取到该键对应的值，因为<code>'_'</code>被“获取任意深度的值”的语法占用（如<code>get(data).store._.price</code>），后者被<code>[[#:filter(predict)|filter]]</code>的简写占用。

<SyntaxHighLight lang="lua">
local data = {
	_ = {
		foo = 'A',
	},
	another = {
		bar = {
			foo = 'B',
		},
	},
}
get(data)._.foo()           --> {'A', 'B'}
get(data):field('_').foo()  --> {'A'}
</SyntaxHighLight>

==== <code>:filter(predict)</code> ====
过滤。

<SyntaxHighLight lang="lua">
> get(data)._.books:items():filter(function (x) return x.price < 10 end).title()
> get(data)._.books[function (x) return x.price < 10 end].title()  -- 这是一个针对数组的简写，与上面等价
{"Sayings of the Century", "Moby Dick"}

> get(data)._:filter(function (x) return type(x) == "number" end)()
{8.95, 12.99, 8.99, 22.99, 399}
</SyntaxHighLight>

==== <code>:items([filter])</code> ====
获取列表的每个项目。如果<code>filter</code>参数不为空，则相当于<code>:items():filter(filter)</code>。

<SyntaxHighLight lang="lua">
> get(data).store.books:items().author()
{"Nigel Rees", "Evelyn Waugh", "J. R. R. Tolkien", "J. R. R. Tolkien"}
</SyntaxHighLight>

==== <code>:values([filter])</code> ====
获取表的每个值，包括列表部分和字典部分。如果<code>filter</code>参数不为空，则相当于<code>:values():filter(filter)</code>。

<SyntaxHighLight lang="lua">
> get(data).store.books[1]:values()()
{"reference", "Nigel Rees", "Sayings of the Century", 8.95}
</SyntaxHighLight>

==== <code>:map(mapper)</code> ====
转换每个数据。

<SyntaxHighLight lang="lua">
> for _, lowered_title in get(data)._.title:map(function (title) return title:lower() end) do print(lowered_title) end
sayings of the century
sword of honour
moby dick
the lord of the rings
</SyntaxHighLight>