tq

README

Query TOML configuration files with the Tq terminal utility

The tq program lets you query TOML configuration files with a sequence of intuitive filters. It works as a regular Unix filter program reading input data from the standard input and producing results to the standard output. Consult the package documentation or check the Usage section to see how you can use tq.

Installation

Install the program and use tq on the command-line to filter TOML files on the terminal.

go install github.com/mdm-code/tq/cmd/tq@latest

Here is how you can get the whole Go package downloaded to fiddle with, but it does not expose any public interfaces in code.

go get github.com/mdm-code/tq

Usage

Enter tq -h to get usage information and the list of options that can be used with the command. Here is table with the supported filter expressions and some examples to get you going on how to use tq in your workflow.

Supported filters

Filter	Expression
identity	.
key	["string"]
index	[0]
iterator	[]
span	[:]

Retrieve IPs from a table of server tables

In the example below, the TOML input file is (1) queried with the key ["servers"], then (2) the retrieved table is converted to an iterator of objects with [], and then (3) the IP address is recovered from each of the objects with the key ["ip"].

tq -q '["servers"][]["ip"]' <<EOF
[servers]

[servers.prod]
ip = "10.0.0.1"
role = "backend"

[servers.staging]
ip = "10.0.0.2"
role = "backend"
EOF

Output:

'10.0.0.1'
'10.0.0.2'

Retrieve selected ports from a list of databases

This example queries the TOML input for the for the all ports aside from the first one assigned to the first database record on the list.

tq -q '.["databases"][0]["ports"][1:][]' <<EOF
databases = [ {enabled = true, ports = [ 5432, 5433, 5434 ]} ]
EOF

Output:

5433
5434

Run inside of a container

If you don't feel like installing tq with go install, you can test tq out running inside of a container with this command:

docker run -i ghcr.io/mdm-code/tq:latest tq -q "['dependencies']['ignore']" <<EOF
[dependencies]
anyhow = "1.0.75"
bstr = "1.7.0"
grep = { version = "0.3.1", path = "crates/grep" }
ignore = { version = "0.4.22", path = "crates/ignore" }
lexopt = "0.3.0"
log = "0.4.5"
serde_json = "1.0.23"
termcolor = "1.1.0"
textwrap = { version = "0.16.0", default-features = false }
EOF

Development

Go through the Makefile to get an idea of the formatting, testing and linting that can be used locally for development purposes.

License

Copyright (c) 2024 Michał Adamczyk.

This project is licensed under the MIT license. See LICENSE for more details.

Documentation

Overview

Package tq encapsulates the logic of the Tq program behind a public interface. It reads input data from the input reader, processes it with the interpreted query string, and writes output data to the output writer.

Index

• type Tq
  • func New(adapter toml.Adapter) *Tq
  • func (t *Tq) Run(input io.Reader, output io.Writer, query string) error
  • func (t *Tq) Validate(query string) error

Examples

• Tq.Run
• Tq.Validate

Types

type Tq

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

Tq accepts TOML data from input and produces the result TOML data to output. The process of data decoding and encoding is handled by the adapter. The query passed to the Run method string is interpreted and executed against the input data to produce the output data.

func New

func New(adapter toml.Adapter) *Tq

New returns a new Tq struct with the provided TOML adapter.

func (*Tq) Run

func (t *Tq) Run(input io.Reader, output io.Writer, query string) error

Run executes the query string against the input data and writes the output data to the output writer.

Example

ExampleTq_Run demonstrates how to use the Tq struct to run a query against TOML data. The example uses a TOML configuration file with two servers and queries the IP address of the beta server. The output is written to the output.

package main

import (
	"bytes"
	"fmt"
	"strings"

	"github.com/mdm-code/tq"
	"github.com/mdm-code/tq/toml"
)

func main() {
	input := strings.NewReader(`
[servers]

[servers.alpha]
ip = "10.0.0.1"
role = "frontend"

[servers.beta]
ip = "10.0.0.2"
role = "backend"
`)
	var output bytes.Buffer
	query := "['servers']['beta']['ip']"
	config := toml.GoTOMLConf{}
	goToml := toml.NewGoTOML(config)
	adapter := toml.NewAdapter(goToml)
	tq := tq.New(adapter)
	_ = tq.Run(input, &output, query)
	fmt.Println(output.String())
}

Output:

'10.0.0.2'

func (*Tq) Validate

func (t *Tq) Validate(query string) error

Validate checks if the query string is syntactically correct.

Example

ExampleTq_Validate shows how to use the Tq struct to validate whether a given query is syntactically correct. The example shows how the error is reported and represented as a string.

package main

import (
	"fmt"

	"github.com/mdm-code/tq"
	"github.com/mdm-code/tq/toml"
)

func main() {
	query := "['servers'][['ip']"
	config := toml.GoTOMLConf{}
	goToml := toml.NewGoTOML(config)
	adapter := toml.NewAdapter(goToml)
	tq := tq.New(adapter)
	err := tq.Validate(query)
	fmt.Println(err)
}

Output:

['servers'][['ip']
            ^
Parser error: expected ']' to terminate selector but got '['