hcledit

README

hcledit

hcledit is a wrapper around the hclwrite package that adds the ability to edit and manipulate HCL documents using a jq-like query/selector syntax.

We provide a Go package and a simple CLI application based on this package. See hcledit command.

NOTE: This is still under heavy development and we don't have enough documentation and we are planing to add breaking changes. Please be careful when using it.

Install

Use go install:

$ go install go.mercari.io/hcledit/cmd/hcledit@latest

Usage

See Go doc.

Examples

The following is an HCL configuration which we want to manipulate.

resource "google_container_node_pool" "nodes1" {
   name = "nodes1"

   node_config {
     preemptible  = false
     machine_type = "e2-medium"
   }
}

To create a new attribute,

editor, _ := hcledit.ReadFile(filename)
editor.Create("resource.google_container_node_pool.*.node_config.image_type", "COS")
editor.OverWriteFile()

resource "google_container_node_pool" "nodes1" {
   name = "nodes1"

   node_config {
     preemptible  = false
     machine_type = "e2-medium"
+    image_type   = "COS"
   }
}

To update the existing attribute,

editor, _ := hcledit.ReadFile(filename)
editor.Update("resource.google_container_node_pool.*.node_config.machine_type", "e2-highmem-2")
editor.OverWriteFile()

resource "google_container_node_pool" "nodes1" {
   name = "nodes1"

   node_config {
     preemptible  = false
-    machine_type = "e2-medium"
+    machine_type = "e2-highmem-2"
   }
}

To delete the existing attribute,

editor, _ := hcledit.ReadFile(filename)
editor.Delete("resource.google_container_node_pool.*.node_config.machine_type")
editor.OverWriteFile()

resource "google_container_node_pool" "nodes1" {
   name = "nodes1"

   node_config {
     preemptible  = false
-    machine_type = "e2-medium"
   }
}

Contribution

During the active development, we unlikely accept PRs for new features but welcome bug fixes and documentation. If you find issues, please submit an issue first.

If you want to submit a PR for bug fixes or documentation, please read the CONTRIBUTING.md and follow the instruction beforehand.

License

The hcledit is released under the MIT License.

Documentation

Overview

Package hcledit is a Go package to edit HCL configurations. Basically, this is just a wrapper of hclwrite package which provides low-level features of generating HCL configurations. But hcledit allows you to access HCL attribute or block by jq-like query and do various manipulations.

Example

package main

import (
	"fmt"
	"strings"

	"go.mercari.io/hcledit"
)

func main() {
	src := `
resource "google_container_node_pool" "nodes1" {
  name = "nodes1"

  node_config {
    preemptible  = false
    machine_type = "e2-medium"
  }

  timeouts {
    create = "30m"
  }
}

resource "google_container_node_pool" "nodes2" {
  name = "nodes2"

  node_config {
    preemptible  = false
    machine_type = "e2-medium"
  }

  timeouts {
    create = "30m"
  }
}

`
	// Read HCL contents.
	editor, _ := hcledit.Read(strings.NewReader(src), "")

	// Create new attribute on the existing block.
	editor.Create("resource.google_container_node_pool.*.node_config.disk_size_gb", "200")

	// Create new block and add some attributes.
	editor.Create("resource.google_container_node_pool.*.master_auth", hcledit.BlockVal())
	editor.Create("resource.google_container_node_pool.*.master_auth.username", "")
	editor.Create("resource.google_container_node_pool.*.master_auth.password", "")

	// Update existing attributes.
	editor.Update("resource.google_container_node_pool.*.node_config.machine_type", "COS")
	editor.Update("resource.google_container_node_pool.*.node_config.preemptible", true)

	// Delete existing attribute and blocks
	editor.Delete("resource.google_container_node_pool.*.timeouts")

	fmt.Printf("%s", editor.Bytes())
}

Output:

resource "google_container_node_pool" "nodes1" {
  name = "nodes1"

  node_config {
    preemptible  = true
    machine_type = "COS"
    disk_size_gb = "200"
  }

  master_auth {
    username = ""
    password = ""
  }
}

resource "google_container_node_pool" "nodes2" {
  name = "nodes2"

  node_config {
    preemptible  = true
    machine_type = "COS"
    disk_size_gb = "200"
  }

  master_auth {
    username = ""
    password = ""
  }
}

Index

• func BlockVal(labels ...string) *handler.BlockVal
• func RawVal(rawString string) *handler.RawVal
• type HCLEditor
  • func New() (*HCLEditor, error)
  • func Read(r io.Reader, filename string) (*HCLEditor, error)
  • func ReadFile(path string) (*HCLEditor, error)
  • func (h *HCLEditor) Bytes() []byte
  • func (h *HCLEditor) Create(queryStr string, value interface{}, opts ...Option) error
  • func (h *HCLEditor) CustomEdit(fn func(*hclwrite.Body) error) error
  • func (h *HCLEditor) Delete(queryStr string, opts ...Option) error
  • func (h *HCLEditor) OverWriteFile() error
  • func (h *HCLEditor) Read(queryStr string, opts ...Option) (map[string]interface{}, error)
  • func (h *HCLEditor) Update(queryStr string, value interface{}, opts ...Option) error
  • func (h *HCLEditor) Write(w io.Writer) error
  • func (h *HCLEditor) WriteFile(path string) error
• type Option
  • func WithAfter(key string) Option
  • func WithComment(comment string) Option
  • func WithNewLine() Option
  • func WithQuerySeparator(r rune) Option
  • func WithReadFallbackToRawString() Option

Examples

• Package

Functions

func BlockVal

func BlockVal(labels ...string) *handler.BlockVal

TODO(slewiskelly): Should these be exported? Users of this package are not allowed to import "go.mercari.io/hcledit/internal/handler" due to visibility of internal packages.

func RawVal

func RawVal(rawString string) *handler.RawVal

TODO(slewiskelly): As above.

Types

type HCLEditor

type HCLEditor struct {
	// contains filtered or unexported fields
}

HCLEditor implements an editor of HCL configuration.

func New

func New() (*HCLEditor, error)

New constructs a new HCL file with no content which is ready to be mutated.

func Read

func Read(r io.Reader, filename string) (*HCLEditor, error)

Read reads HCL file from the given io.Reader and returns operation interface for it.

func ReadFile

func ReadFile(path string) (*HCLEditor, error)

ReadFile reads HCL file in the given path and returns operation interface for it.

func (*HCLEditor) Bytes

func (h *HCLEditor) Bytes() []byte

Bytes returns a buffer containing the source code resulting from the tokens underlying the receiving file. If any updates have been made via the AST API, these will be reflected in the result.

func (*HCLEditor) Create

func (h *HCLEditor) Create(queryStr string, value interface{}, opts ...Option) error

Create creates attributes and blocks matched with the given query with the given value. The value can be any type and it's transformed into HCL type inside.

func (*HCLEditor) CustomEdit

func (h *HCLEditor) CustomEdit(fn func(*hclwrite.Body) error) error

CustomEdit executes a custom function on the underlying file

func (*HCLEditor) Delete

func (h *HCLEditor) Delete(queryStr string, opts ...Option) error

Delete deletes attributes and blocks matched with the given query.

It returns error if it does not match any key.

func (*HCLEditor) OverWriteFile

func (h *HCLEditor) OverWriteFile() error

OverWriteFile writes the new contents to the file that has first been read via ReadFile.

func (*HCLEditor) Read

func (h *HCLEditor) Read(queryStr string, opts ...Option) (map[string]interface{}, error)

Read returns attributes and blocks matched with the given query. The results are map of mached key and its value.

It returns error if it does not match any key.

func (*HCLEditor) Update

func (h *HCLEditor) Update(queryStr string, value interface{}, opts ...Option) error

Update replaces attributes and blocks which matched with its key and given query with the given value. The value can be any type and it's transformed into HCL type inside.

By default, it returns error if the does not matched with any key. You must create value before update.

func (*HCLEditor) Write

func (h *HCLEditor) Write(w io.Writer) error

Write writes the new contents to the given io.Writer.

func (*HCLEditor) WriteFile

func (h *HCLEditor) WriteFile(path string) error

WriteFile writes the new contents to the given file, creating it if it does not exist.

type Option

type Option func(*option)

Option configures specific behavior for specific HCLEditor operations. TODO(slewiskelly): Not all options are applicable to all operations, maybe options should be specific to each kind of operation?

func WithAfter

func WithAfter(key string) Option

func WithComment

func WithComment(comment string) Option

WithComment provides comment to put together when creating.

func WithNewLine

func WithNewLine() Option

WithNewLine

func WithQuerySeparator

func WithQuerySeparator(r rune) Option

This sets a separator for queryStr in HCLEditor funcs. The default separator is ".".

func WithReadFallbackToRawString

func WithReadFallbackToRawString() Option

This provides a fallback to return the raw string of the value if we could not parse it. If this option is provided to HCLEditor.Read(), the error return value will signal fallback occurred.