> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 函数

> ArcScript 函数格式化器，用于 CSV、JSON、XML 和实用操作，可在不需要管道输入值的情况下生成输出。

export const siteNameShort = "知行之桥";

可以将函数视为一种特殊类型的格式化器，它会生成输出值，但不像标准格式化器那样需要输入。函数可以单独使用，也可以作为更复杂表达式的开头，并在其后通过管道接入其他格式化器。例如，`[vault(foo)]` 可以单独解析，也可以作为表达式的开头使用（例如，`[vault(foo) | equals(bar)]` 用于检查 `foo` 配置库值是否等于 `bar`）。

## CSV 函数

### csv(value)

在从 CSV 文件加载数据后使用。`csvListRecords` 操作会解析 CSV 文件，而 CSV 格式化器会像其他格式化器一样，通过从 CSV 文档生成值来运行。

* **value**：用于查找值的 CSV 列标题字符串。如果 CSV 文件没有标题，并且你将 *requireheader* 属性设置为 false，则可以通过通用索引（c1、c2、c3、...）访问列。

#### 示例

在以下片段中，CSV 文档在 {siteNameShort}Script 的内存中定义。

```xml theme={null}
<arc:set attr="data" value=
"column1,column2,column3
entry1,entry2,entry3
entry4,entry5,entry6"
/>
```

接下来，调用 `csvListRecords` 操作，并从示例 CSV 文档显示 CSV 格式化器。

```xml theme={null}
<arc:call op="csvListRecords">
Row [_index] values: [csv('column1')], [csv('column2')], [csv('column3')]
</arc:call>
```

运行此代码会显示以下输出：

```
Row 1 values: entry1, entry2, entry3
Row 2 values: entry4, entry5, entry6
```

## JSON 函数

### hasjsonpath(jsonpath)

检查输入的 jsonpath 是否存在于 JSON 文档中，并返回布尔值（true/false）。

* **jsonpath**：要检查的相对 jsonpath。

#### 示例

```xml theme={null}
<arc:set attr="json.text">
  {
    "key1": null,
    "key2": "this is a string",
    "key3": "hello world",
    "key4": 123,
    "key5": {},
    "key6": \[],
    "key7": true
  }
</arc:set>
<arc:set attr="json.jsonpath" value="/json"/>
<arc:call op="jsonDOMSearch" in="json" out="result">
  <!-- This checks to see if the desired jsonpath exists and throws an error if it does not.  -->
  <arc:if exp="[hasjsonpath(key10) | equals(false)]">
    <arc:throw code="noJSONPath" desc="The jsonpath you were looking for does not exist!" />
  </arc:if>
</arc:call>
```

### isjsonpathnull(jsonpath, \[ifTrue], \[ifFalse])

检查输入的 jsonpath；如果 jsonpath 为 null 或不存在，则返回布尔值（true/false）。

* **jsonpath**：要检查的可选相对 json。
* **ifTrue**：如果格式化器解析为 true，则返回的可选值。
* **ifFalse**：如果格式化器解析为 false，则返回的可选值。

#### 示例

```xml theme={null}
<arc:set attr="json.text">
  {
    "key1": null,
    "key2": "this is a string",
    "key3": "hello world",
    "key4": 123,
    "key5": {},
    "key6": \[],
    "key7": true
  }
</arc:set>
<arc:set attr="json.jsonpath" value="/json"/>
<arc:call op="jsonDOMSearch" in="json" out="result">
  <arc:if exp="[IsJSONPathNull(key1) | equals(true)]" >
    <!-- This executes because key1 has a value of null -->
    <arc:set attr="_log.info" value="The jsonpath for key1 either has a value of null or does not exist." />
    <!-- Overriding the default true/false output of the formatter to 1/0 -->
    <arc:if exp="[IsJSONPathNull(key10, 1, 0) | equals(1)]" >
      <!-- This executes because key10 does not exist within the input json text -->
      <arc:set attr="_log.info" value="The jsonpath for key10 either has a value of null or does not exist." />
    </arc:if>
  </arc:if>
</arc:call>
```

### jsonpath(jsonpath)

可以在调用具有可用 JSON DOM 的 JSON 操作时使用此格式化器。可以使用 [jsonDOMSearch](../operations/op-json-dom-search) 和 [jsonDOMGet](../operations/op-json-dom-get) 操作来解析 JSON 文档。jsonpath 格式化器是 DOM 对象的格式化器，它像其他格式化器一样通过从 JSON 文档生成值来运行。它会返回 JSON 文档的当前 jsonpath 位置。也可以提供相对 jsonpath 字符串来查找关联的 JSON 值。

* **jsonpath**：用于查找关联 JSON 值的可选相对 jsonpath。

#### 示例

```xml theme={null}
<arc:set attr="json.text">
  {
    "key1": null,
    "key2": "this is a string",
    "key3": "hello world",
    "key4": 123,
    "key5": {},
    "key6": \[],
    "key7": true
  }
</arc:set>
<arc:set attr="json.jsonpath" value="/json"/>
<arc:call op="jsonDOMSearch" in="json" out="result">
  <!-- This prints 'I just want to say, hello world!' to the application log -->
  <arc:set attr="_log.info" value="I just want to say, [jsonpath(key3)]!"/>
</arc:call>
```

### jsonsubtree(jsonpath)

可以使用 jsonsubtree 从嵌套 JSON 结构中解析 JSON 子树。

* **jsonpath**：可选的相对 jsonpath 字符串，用于指示从结构的哪个层级开始。

#### 示例

以下脚本在 JSON 数据的 `/json/Event/Attendees` 对象下包含三个 `User` 条目。`Attendees` 对象是根对象的子树。

```xml theme={null}
<arc:setc attr="json.text">
{
  "Event": {
    "Subject": "Meeting",
    "Attendees": {
      "User": [
        {
          "Code": "1",
          "Name": "Jane Doe"
        },
        {
          "Code": "2",
          "Name": "John Smith"
        },
        {
          "Code": "3",
          "Name": "Alex Johnson"
        }
      ]
    }
  }
}
</arc:setc>
<arc:set attr="json.jsonpath" value="/json/Event/Attendees" />
<arc:call op="jsonDOMSearch" in="json">
<arc:set attr="_log.info">  <!-- Logging the results to the application log -->
[jsonsubtree(.)]  <!-- Insert your desired jsonpath inside the parentheses -->
</arc:set>
</arc:call>
```

在此示例中，jsonpath 是 `.` 字符，它指示脚本根据其在根对象中的位置使用当前 jsonpath。这里，该路径为 `/json/Event/Attendees`，会返回全部三个条目。

下图显示了它在**日志**页面的[应用程序日志](../../getting-started/administration/activity#application-logs)中的显示方式：

<img src="https://mintcdn.com/qiao/bVtjD3fvHFZBo1vE/public/images/jsonsubtree_activity_log.png?fit=max&auto=format&n=bVtjD3fvHFZBo1vE&q=85&s=64e4d72d16d445c1e3837f6ff01bb666" alt="jsonsubtree result in the Activity log" width="800" data-path="public/images/jsonsubtree_activity_log.png" />

以下是原始 JSON 子树结果：

```
"Attendees": {
      "User": [
        {
          "Code": "1",
          "Name": "Jane Doe"
        },
        {
          "Code": "2",
          "Name": "John Smith"
        },
        {
          "Code": "3",
          "Name": "Alex Johnson"
        }
      ]
    }
```

若要仅显示 `/json/Event/Attendees` 中第二次出现的 `User` jsonpath 的子树，请将 `jsonsubtree` 格式化器调用中的路径替换为 `jsonsubtree(User/\[2\])`。这会产生以下输出：

```
{
  "Code": "2",
  "Name": "John Smith"
}
```

### jsontype(jsonpath)

返回当前 JSON 名称-值对的数据类型（字符串、数字、对象、数组或布尔值）。

* **jsonpath**：用于查找关联 JSON 值的可选相对 jsonpath。

#### 示例

```xml theme={null}
<arc:set attr="json.text">
  {
    "key1": null,
    "key2": "this is a string",
    "key3": "hello world",
    "key4": 123,
    "key5": {},
    "key6": \[],
    "key7": true
  }
</arc:set>
<arc:set attr="json.jsonpath" value="/json"/>
<arc:call op="jsonDOMSearch" in="json" out="result">
  <!-- Creating some output data that describes various elements of the input json -->
  <arc:set attr="output.data">The jsontype of key4 is [jsontype(key4)]
The jsontype of key5 is [jsontype(key5)]
The jsontype of key6 is [jsontype(key6)]
The jsontype of key7 is [jsontype(key7)]
  </arc:set>
</arc:call>

<arc:set attr="output.filename" value="output.txt" />
<arc:push item="output" /> 

<!-- contents of output.txt -->

The jsontype of key4 is NUMBER
The jsontype of key5 is OBJECT
The jsontype of key6 is ARRAY
The jsontype of key7 is BOOL
```

## XML 函数

### hasxpath(xpath)

检查输入的 xpath 是否存在于 XML 文档中，并返回布尔值（true/false）。

* **xpath**：要检查的相对 xpath。

#### 示例

```xml theme={null}
<arc:set attr="xml.text">
  <Items>
    <Foo>Bar</Foo>
    <Bar>Foo</Bar>
  </Items>
</arc:set>
<arc:set attr="xml.xpath" value="/Items"/>
<arc:call op="xmlDOMSearch" in="xml" out="result">
  <!-- This checks to see if the desired xpath exists and throws an error if it does not  -->
  <arc:if exp="[hasxpath(helloworld) | equals(false)]">
    <arc:throw code="noXPath" desc="The xpath you were looking for does not exist!" />
  </arc:if>
</arc:call>
```

### isxpathnull(xpath, \[ifTrue], \[ifFalse])

检查输入的 xpath；如果 xpath 为 null 或不存在，则以 `xsi:nil` XML 属性（`xsi:nil="true/false"`）的形式返回布尔值。使用 *ifTrue* 和 *ifFalse* 参数指定条件满足和不满足时的替代值。

* **xpath**：要检查的可选相对 xpath。
* **ifTrue**：如果格式化器解析为 true，则返回的可选值。
* **ifFalse**：如果格式化器解析为 false，则返回的可选值。

#### 示例

```xml theme={null}
<arc:set attr="xml.text">
  <Items>
    <Foo>Bar</Foo>
    <Bar>Foo</Bar>
    <helloworld xsi:nil="true" />
  </Items>
</arc:set>
<arc:set attr="xml.xpath" value="/Items"/>
<arc:call op="xmlDOMSearch" in="xml" out="result">
  <arc:if exp="[IsXPathNull(helloworld) | contains(true)]" >
    <!-- This executes because the 'helloworld' has the xsi:nil attribute set to true -->
    <arc:set attr="_log.info" value="The xpath for 'helloworld' either has a value of null or does not exist." />
    <!-- Overriding the default output of the formatter to use true/false. If the exp is true, the script inside runs. -->
    <arc:if exp="[IsXPathNull(waldo, true, false)]" >
      <!-- This executes because the 'waldo' element does not exist within the input xml text -->
      <arc:set attr="_log.info" value="The xpath for 'waldo' either has a value of null or does not exist." />
    </arc:if>
  </arc:if>
</arc:call>
```

### xpath(xpath)

在调用具有可用 XML DOM 的 XML 操作时使用。可以使用 [xmlDOMSearch](../operations/op-xml-dom-search) 和 [xmlDOMGet](../operations/op-xml-dom-get) 操作来解析 XML 文档。XPath 格式化器是 DOM 对象的格式化器，它像其他格式化器一样通过从 XML 文档生成值来运行。它会返回 XML 文档的当前 XPath 位置。

* **xpath**：用于查找关联 XML 值的可选相对 XPath 字符串。

#### 示例

在以下片段中，XML 文档在 {siteNameShort}Script 的内存中定义。

```xml theme={null}
<arc:set attr="text">
  <root>
    <A>Value_One</A>
    <A>
      <B>
        <C>Value_Two</C>
      </B>
    </A>
    <A>
      <B>Value_Three</B>
    </A>
  </root>
</arc:set>
```

在此片段中，调用 [xmlDOMSearch](../operations/op-xml-dom-search) 操作，并从示例 XML 文档显示 XPath 格式化器。

```xml theme={null}
<arc:call op="xmlDOMSearch?xpath=/root/A">
  Current XPath is [xpath] and the 'B' element value is [xpath(B) | empty("not present")]
</arc:call>
```

针对前面的 XML 文档运行时，此代码会显示以下输出。

```
Current XPath is /root/A[1] and the 'B' element value is not present
Current XPath is /root/A[2] and the 'B' element value is not present
Current XPath is /root/A[3] and the 'B' element value is Value_Three
```

XPath 格式化器会显示迭代的三个 `A` 元素，但只显示最终 `B` 元素中的 `Value_Three`，因为 `[xpath(B)]` 会忽略其他元素中的值。

### xpathcount(xpath)

类似于 XPath 格式化器，但它返回与所提供 XPath 匹配的元素的*计数*。在调用具有可用 XML DOM 的 XML 操作时使用。可以使用 [xmlDOMSearch](../operations/op-xml-dom-search) 和 [xmlDOMGet](../operations/op-xml-dom-get) 操作来解析 XML 文档。XPathCount 格式化器是 DOM 对象的格式化器，它像其他格式化器一样通过从 XML 文档生成计数来运行。

* **xpath**：用于计算计数的可选相对 XPath 字符串。

#### 示例

```xml theme={null}
<arc:set attr="xml.xpath" value="/Items/Cars/Subaru" />
<arc:set attr="xml.text">
 <Items>
  <Cars>
    <Subaru>
      <Color>Blue</Color>
      <Year>2017</Year>
    </Subaru>
    <Honda>
      <Color>Red</Color>
    </Honda>
  </Cars>
</Items>
</arc:set>
<arc:call op="xmlDOMSearch" in="xml" out="result">
  <!-- xpathcount is a context-sensitive function in arcscript. If an xml document is loaded in a 
       search, xpathcount returns the count of the number of elements that match the provided xpath. -->
  <arc:set attr="output.Data" value="[xpathcount('/Items/Cars/*/Color')]" />
</arc:call>

<arc:set attr="output.filename" value="test.txt" />
<arc:push item="output" />
```

运行此代码时，它会返回 `2` 作为输出。

### xsubtree(xpath)

从嵌套 XML 结构中解析 XML 树。

* **xpath**：可选的相对 XPath 字符串，用于指示从结构的哪个层级开始。

#### 示例

在下面的示例 XML 文档中，`/Event/Attendees` 下有三个条目。

```xml theme={null}
<arc:set attr="xml.text">
<Event>
    <Subject>Meeting</Subject>
    <Attendees>
        <User>
            <Code>1</Code>
            <Name>TEST1</Name>
        </User>
        <User>
            <Code>2</Code>
            <Name>TEST2</Name>
        </User>
        <User>
            <Code>3</Code>
            <Name>TEST3</Name>
        </User>
    </Attendees>
</Event>
</arc:set>

<arc:set attr="xml.xpath" value="/Event/Attendees" />
<arc:call op="xmlDOMSearch" in="xml">
  [xsubtree(.)]  <!-- Insert desired xpath in parentheses  -->
</arc:call>
```

`xsubtree` 命令中的 `.` 字符指示脚本使用当前 xpath。在此示例中，该路径为 `/Event/Attendees`，会返回全部三个条目：

```xml theme={null}
<User>
  <Code>1</Code>
  <Name>TEST1</Name>
</User>
<User>
  <Code>2</Code>
  <Name>TEST2</Name>
</User>
<User>
  <Code>3</Code>
  <Name>TEST3</Name>
</User>
```

若要仅显示 `/Event/Attendees` xpath 中第二次出现的 `User` 子树，请将命令替换为 `xsubtree(User[2])`。其结果为：

```xml theme={null}
<User>
  <Code>2</Code>
  <Name>TEST2</Name>
</User>
```

## 其他函数

### guid(includehyphens)

生成全局唯一标识符 (GUID) 值。默认情况下，格式化器会在单个未格式化字符串中返回所有字符。要包含符合标准 8-4-4-4-12 GUID 格式的连字符，请使用 *includehyphens* 参数并将其设置为 *true*。

* **includehyphens**：设置为 *true* 可在返回的 GUID 中包含连字符。

此格式化器不会修改输入属性（变量），因此不需要此类输入属性。

#### 示例

```xml theme={null}
<arc:set attr="myGUID" value="[guid(true)]" />
```

### vault(ItemName, \[ifnotexists])

返回[全局设置配置库](../../getting-started/administration/settings/global-settings-vault)中与所提供 *ItemName* 值匹配的配置库项目值。默认情况下，如果配置库项目不存在，则会抛出错误。

* **ItemName**：要检索的配置库项目名称。
* **ifnotexists**：为防止配置库项目不存在时抛出错误，请提供此可选参数和默认值，例如 `value does not exist`。当不存在具有指定 *ItemName* 的配置库项目时，会返回该值。

<Note>在脚本上下文中引用加密配置库项目时请务必小心，以确保日志中不包含敏感信息。</Note>

#### 示例

```xml theme={null}
<arc:set attr="URLtoResource" value="[Vault(commonURL)]" />
```