hclquery

README

# Overview
The purpose of the hclquery package is simple; given a hcl body and a query
string, it executes the query against the body and returns back a list of
blocks that satisfies the query.

# The Query
### Grammer

```
Expr         ::= Segment ( '/' Segment )*

Segment      ::= Ident
                 | Ident '{' Predicate '}'
                 | Ident '{' Predicate '}' '[' NUM ']'
                 | Block
                 | Block '{' Predicate '}'

Block        ::= Ident '[' NUM ']'
               | Ident ':' Ident

Predicate    ::= Ident
               | Ident '=' Literal
Literal      ::= ''' CHARACTERS '''
               | '"' CHARACTERS '"'
```

### Precedence
1. `=`
2. `/`, `:`, `[]` and `{}`

### Associativity
- `/`, `:`, `[]` and `{}` are left-associative.
- `=` is right-associative.

### Examples
`terraform`
find a block of type `terraform`.

```
terraform {
  ...
}
```

`terraform/required_providers`
find a block of type `provider` that is nested inside a block of type `terraform`.
```
terraform {
  ...
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.11.0"
    }
  }
	...
}
```

`terraform/backend:s3`
find a block of type `backend` and label `s3` that is nested inside a block of type `terraform`
```
terraform {
  backend "s3" {
    ...
  }
	...
}
```

`terraform/backend:s3{region}`
find a block of type `backend` with a label `s3` and has an attribute called `region`.

```
terraform {
  backend "s3" {
		...
    region = "eu-west-2"
		...
  }
	...
}
```

`terraform/backend:s3{region='eu-west-2'}`
find a block of type `backend` with a label `s3` and has an attribute called `region` with a value of `eu-west-2`

```
terraform {
  backend "s3" {
		...
    region = "eu-west-2"
		...
  }
	...
}
```

Documentation

Overview

The purpose of the hclquery package is simple; given a hcl body and a query string, it executes the query against the body and returns back a list of blocks that satisfies the query.

The Query Grammer

Expr         ::= Segment ( '/' Segment )*

Segment      ::= Ident

	| Ident '{' Predicate '}'
	| Ident '{' Predicate '}' '[' NUM ']'
	| Block
	| Block '{' Predicate '}'

Block        ::= Ident '[' NUM ']'

	| Ident ':' Ident

Predicate    ::= Ident

	| Ident '=' Literal

Literal      ::= ”' CHARACTERS ”'

	| '"' CHARACTERS '"'

Examples

1. `terraform`

find a block of type `terraform`.

terraform {
  ...
}

2. `terraform/required_providers`

find a block of type `provider` that is nested inside a block of type `terraform`.

terraform {
  ...
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.11.0"
    }
  }
	...
}

3. `terraform/backend:s3`

find a block of type `backend` and label `s3` that is nested inside a block of type `terraform`

terraform {
  backend "s3" {
    ...
  }
	...
}

4. `terraform/backend:s3{region}`

find a block of type `backend` with a label `s3` and has an attribute called `region`.

terraform {
  backend "s3" {
		...
    region = "eu-west-2"
		...
  }
	...
}

5. `terraform/backend:s3{region='eu-west-2'}`

find a block of type `backend` with a label `s3` and has an attribute called `region` with a value of `eu-west-2`

terraform {
  backend "s3" {
		...
    region = "eu-west-2"
		...
  }
	...
}

Index

• func Query(b hcl.Body, path string) (hclsyntax.Blocks, error)
• type Compilation
  • func Compile(path string) (*Compilation, error)

Functions

func Query

func Query(b hcl.Body, path string) (hclsyntax.Blocks, error)

Given a hcl body, and a query string, it returns an array of hcl blocks that matches the given query.

Types

type Compilation

type Compilation struct {
	// Invoking this method, and passing list of hcl Blocks, it executes the query
	// against the given list and returning a list of blocks that statisfies the
	// query.
	Exec execFunc
}

A result of compiling a query string.

func Compile

func Compile(path string) (*Compilation, error)

Compiles the query string and returns a Compilation.