yaml-go-edit

High-performance YAML editing toolkit with advanced node manipulation capabilities.

---

CHINESE README

中文说明

Main Features

🎯 Smart YAML Manipulation: Route-based field access with dot-notation path navigation
⚡ Node Transformation: Transform functions supporting complex YAML node modifications
🔄 Structure Preservation: Maintains YAML document format and structure completeness
🌍 Nested Navigation: Deep navigation support across complex nested YAML structures
📋 Flexible API: Both low-end node operations and high-end convenience methods

Installation

go get github.com/go-xlan/yaml-go-edit

Usage

Basic Field Modification

This example shows how to change a YAML field value using dot notation path.

package main

import (
	"fmt"

	"github.com/go-xlan/yaml-go-edit/yamlv3edit"
)

func main() {
	config := []byte(`
database:
  host: localhost
  port: 5432
  username: admin
`)

	// Update database host
	updated := yamlv3edit.ModifyYamlFieldValue(config, "database.host", "prod.database.com")
	fmt.Println(string(updated))
}

⬆️ Source: Source

Advanced Node Transformation

This example demonstrates custom node transformations with type changes and comments.

package main

import (
	"fmt"

	"github.com/go-xlan/yaml-go-edit/yamlv3edit"
	"gopkg.in/yaml.v3"
)

func main() {
	data := []byte(`
settings:
  timeout: "60"
`)

	// Add comments and change types
	result := yamlv3edit.ChangeYamlFieldValue(data, []string{"settings", "timeout"}, func(node *yaml.Node) {
		node.Value = "30"
		node.Tag = "!!int"
		node.LineComment = "timeout in seconds"
	})
	
	fmt.Println(string(result))
}

⬆️ Source: Source

API Reference

Core Functions

• ModifyYamlFieldValue(data []byte, path string, value string) []byte - Update field using dot notation
• ChangeYamlFieldValue(data []byte, route []string, change func(*yaml.Node)) []byte - Transform nodes with custom logic
• LookupSubNode(node *yaml.Node, path string) *yaml.Node - Find node using dot-separated path
• SearchSubNode(node *yaml.Node, route []string) *yaml.Node - Navigate using route slice
• RecurseSearch(node *yaml.Node, route []string) *yaml.Node - Recursive navigation through mappings

Examples

Advanced Configurations

Update nested TLS settings:

result := yamlv3edit.ModifyYamlFieldValue(data, "server.ssl.certificate", "/path/to/cert.pem")

Update list-based configuration:

result := yamlv3edit.ModifyYamlFieldValue(data, "logging.outputs.0", "console")

Environment-Specific Updates

Switch to production database:

result := yamlv3edit.ModifyYamlFieldValue(data, "database.pool.max_connections", "100")

Update API endpoints:

result := yamlv3edit.ModifyYamlFieldValue(data, "services.auth.endpoint", "https://auth.prod.com")

Complex Node Transformations

Add head comment block:

yamlv3edit.ChangeYamlFieldValue(data, []string{"cache"}, func(node *yaml.Node) {
    node.HeadComment = "# Cache configuration\n# Updated: 2024-01-01\n"
})

Convert and add multiple comments:

yamlv3edit.ChangeYamlFieldValue(data, []string{"database", "pool", "timeout"}, func(node *yaml.Node) {
    node.Value = "30"
    node.Tag = "!!int"
    node.LineComment = "seconds"
    node.FootComment = "# connection timeout setting"
})

Deep Structure Navigation

Navigate deep nested configs:

config := yamlv3edit.SearchSubNode(&rootNode, []string{"microservices", "payment", "database", "replica"})

Check if path exists before updates:

if yamlv3edit.LookupSubNode(&rootNode, "features.test.enabled") != nil {
    // Path exists, safe to update
}

📄 License

MIT License. See LICENSE.

---

🤝 Contributing

Contributions are welcome! Report bugs, suggest features, and contribute code:

• 🐛 Found a bug? Open an issue on GitHub with reproduction steps
• 💡 Have a feature idea? Create an issue to discuss the suggestion
• 📖 Documentation confusing? Report it so we can improve
• 🚀 Need new features? Share the use cases to help us understand requirements
• ⚡ Performance issue? Help us optimize through reporting slow operations
• 🔧 Configuration problem? Ask questions about complex setups
• 📢 Follow project progress? Watch the repo to get new releases and features
• 🌟 Success stories? Share how this package improved the workflow
• 💬 Feedback? We welcome suggestions and comments

---

🔧 Development

New code contributions, follow this process:

1. Fork: Fork the repo on GitHub (using the webpage UI).
2. Clone: Clone the forked project (git clone https://github.com/yourname/repo-name.git).
3. Navigate: Navigate to the cloned project (cd repo-name)
4. Branch: Create a feature branch (git checkout -b feature/xxx).
5. Code: Implement the changes with comprehensive tests
6. Testing: (Golang project) Ensure tests pass (go test ./...) and follow Go code style conventions
7. Documentation: Update documentation to support client-facing changes and use significant commit messages
8. Stage: Stage changes (git add .)
9. Commit: Commit changes (git commit -m "Add feature xxx") ensuring backward compatible code
10. Push: Push to the branch (git push origin feature/xxx).
11. PR: Open a pull request on GitHub (on the GitHub webpage) with detailed description.

Please ensure tests pass and include relevant documentation updates.

---

🌟 Support

Welcome to contribute to this project via submitting merge requests and reporting issues.

Project Support:

• ⭐ Give GitHub stars if this project helps you
• 🤝 Share with teammates and (golang) programming friends
• 📝 Write tech blogs about development tools and workflows - we provide content writing support
• 🌟 Join the ecosystem - committed to supporting open source and the (golang) development scene

Have Fun Coding with this package! 🎉

---

GitHub Stars