pkl/stdlib/xml.pkl

//===----------------------------------------------------------------------===//
// Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//===----------------------------------------------------------------------===//

/// An XML renderer.
@ModuleInfo { minPklVersion = "0.31.0" }
module pkl.xml

/// Renders values as XML.
///
/// Values are rendered as follows depending on their type:
///
/// - `Int`, `Float`, `Boolean`, `String`: XML text node
/// - `List`, `Set`, `Listing`: sequence of XML text nodes or XML elements (depending on element types)
/// - `Map<String, ?>`, `Mapping<String, ?>`, `Typed`: sequence of XML elements (`null` values are skipped)
/// - `Dynamic`: sequence of XML text nodes and/or XML elements (depending on member types; `null` value are skipped)
///
/// For more control over XML rendering, use [Element()], [Inline], [Comment], and [CData].
/// These DOM-style objects can be used exclusively or mixed and matched with "normal" Pkl objects.
///
/// To set the name and attributes of the XML document's root element,
/// use [rootElementName] and [rootElementAttributes].
///
/// The [Property] annotation can be used to change how a property name renders into XML.
///
/// Example:
/// ```
/// import "pkl:xml"
///
/// @xml.Property { name = "wing_span" }
/// wingSpan: Int
/// ```
class Renderer extends ValueRenderer {
  extension = "xml"

  /// The characters to use for indenting output.
  indent: String = "  "

  /// The XML version to use.
  xmlVersion: *"1.0" | "1.1"

  /// The name of the XML document's root element.
  rootElementName: String(!isEmpty) = "root"

  /// The attributes of the XML document's root element.
  rootElementAttributes: Mapping<String(!isEmpty), String | Boolean | Int | Float>

  external function renderDocument(value: Any): String

  external function renderValue(value: Any): String
}

/// Annotate properties of classes and modules with this class to override how a [Renderer]
/// interprets a property's name.
@Since { version = "0.31.0" }
class Property extends ConvertProperty {
  /// The new name to use for the annotated property when rendered by [Renderer].
  name: String

  render = (prop, renderer) -> if (renderer is Renderer) Pair(name, prop.value) else prop
}

/// Creates an XML element with the given name.
///
/// Use this method to directly define an XML element
/// instead of relying on the default rendering of Pkl values.
///
/// To define the XML element's attributes, set the [attributes] property of the `Element` object:
/// ```
/// order = xml.Element("order") {
///   attributes {
///     ["date"] = "2020-03-21"
///   }
/// }
/// ```
///
/// To define the XML element's content, add child values (normally also called "elements") to the `Element` object:
/// ```
/// order = (xml.Element("order")) {       // element with one child
///   (xml.Element("item")) {              // element with two children
///     (xml.Element("name")) { "banana" } // element with one child
///     (xml.Element("quantity")) { 42 }   // element with one child
///   }
/// }
/// ```
function Element(_name: String(!isEmpty)): Dynamic = new {
  _isXmlElement = true
  name = _name
  attributes = new Mapping {}
  isBlockFormat = true
}

/// Creates an [Inline] directive for [_value].
function Inline(_value: Object | Collection | Map): Inline = new { value = _value }

/// Inlines the members of [value] into the enclosing XML element,
/// without rendering an XML element for [value] itself.
class Inline {
  value: Object | Collection | Map
}

/// Creates an XML [Comment] with the given [_text].
function Comment(_text: String): Comment = new { text = _text }

/// An XML comment.
class Comment {
  text: String(!contains("--"))
  isBlockFormat: Boolean = true
}

/// Creates an XML [CData] section with the given [_text].
function CData(_text: String): CData = new { text = _text }

/// An XML CDATA section.
class CData {
  text: String
}