Documentation
¶
Overview ¶
Example ¶
package main
import (
"context"
"fmt"
"github.com/hashicorp/hcp/internal/pkg/heredoc"
"github.com/hashicorp/hcp/internal/pkg/iostreams"
)
func main() {
io, _ := iostreams.System(context.Background())
out := heredoc.New(io).Mustf(`
This is an example of documenting a command. You can format in values %s you want.
Really long lines will automatically get wrapped for you. So you don't need to worry about being super rigorous about where you wrap a line.
However if you have a block of text that you want to preserve the formatting of, you can use the PreserveNewLines function as shown below.
{{ PreserveNewLines }}
{
"description": "JSON block to preserve the formatting of",
"cool": true
}
{{ PreserveNewLines }}
You can also colorize and stylize text. This is useful if you want to highlight a command.
Such as, run {{ Bold "hcp your command" }} to do awesome things.
The available style functions are: Bold, Faint, Italic, Underline, Blink, CrossOut.
You can color output with the Color function. It is invoked as Color <text color> <optional foreground> "text".
The valdid colors are: red, green, yellow, orange, gray, white, black, or #<hex>. The case doesn't matter.
For example, {{ Color "Red" "this could be an error" }}.
You may have noticed that all these lines have an indent. heredoc will automatically dedent for you.
But you can still further indent and it will be maintained for you.
Lastly, blank spaces at the start and end will be stripped so that you can start your text on a new line and end it like this.
`, "wherever")
fmt.Fprintln(io.Out(), out)
}
Output: This is an example of documenting a command. You can format in values wherever you want. Really long lines will automatically get wrapped for you. So you don't need to worry about being super rigorous about where you wrap a line. However if you have a block of text that you want to preserve the formatting of, you can use the PreserveNewLines function as shown below. { "description": "JSON block to preserve the formatting of", "cool": true } You can also colorize and stylize text. This is useful if you want to highlight a command. Such as, run hcp your command to do awesome things. The available style functions are: Bold, Faint, Italic, Underline, Blink, CrossOut. You can color output with the Color function. It is invoked as Color <text color> <optional foreground> "text". The valdid colors are: red, green, yellow, orange, gray, white, black, or #<hex>. The case doesn't matter. For example, this could be an error. You may have noticed that all these lines have an indent. heredoc will automatically dedent for you. But you can still further indent and it will be maintained for you. Lastly, blank spaces at the start and end will be stripped so that you can start your text on a new line and end it like this.
Example (Second) ¶
This example demonstrates how to use codeblocks
package main
import (
"context"
"fmt"
"github.com/hashicorp/hcp/internal/pkg/heredoc"
"github.com/hashicorp/hcp/internal/pkg/iostreams"
)
func main() {
io, _ := iostreams.System(context.Background())
out := heredoc.New(io).Must(`
When displaying code blocks,the heredoc should have no indentation.
The code block gets defined then passed to the code block function.
{{ define "example" -}} {
"bindings": [
{
"role_id": "ROLE_ID",
"members": [
{
"member_id": "PRINCIPAL_ID",
"member_type": "USER" | "GROUP" | "SERVICE_PRINCIPAL",
}
]
}
],
"etag": "ETAG",
} {{- end }}
{{- CodeBlock "example" "json" | Color "green" }}
`)
fmt.Fprintln(io.Out(), out)
}
Output: When displaying code blocks,the heredoc should have no indentation. The code block gets defined then passed to the code block function. { "bindings": [ { "role_id": "ROLE_ID", "members": [ { "member_id": "PRINCIPAL_ID", "member_type": "USER" | "GROUP" | "SERVICE_PRINCIPAL", } ] } ], "etag": "ETAG", }
Example (Third) ¶
This example demonstrates how to use the mdCodeOrBold template
package main
import (
"context"
"fmt"
"github.com/hashicorp/hcp/internal/pkg/heredoc"
"github.com/hashicorp/hcp/internal/pkg/iostreams"
)
func main() {
io, _ := iostreams.System(context.Background())
out := heredoc.New(io).Must(`
To display text as bold for non-markdown output and as a code block for
markdown output, use the mdCodeOrBold template.
The {{ template "mdCodeOrBold" "hcp projects iam read-policy" }} command
is used to display the IAM policy for a project.
`)
fmt.Fprintln(io.Out(), out)
}
Output: To display text as bold for non-markdown output and as a code block for markdown output, use the mdCodeOrBold template. The hcp projects iam read-policy command is used to display the IAM policy for a project.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config stores configuration for the formatter. The values can be set by constructing the formatter with ConfigOptions.
type ConfigOption ¶
type ConfigOption func(c *Config)
ConfigOption allow configuring the formatters configuration.
func WithNoWrap ¶
func WithNoWrap() ConfigOption
WithNoWrap does not wrap the line. This is useful when the output will be passed to other functions that have their own wrapping.
func WithPreserveNewlines ¶
func WithPreserveNewlines() ConfigOption
WithPreserveNewlines is used to disable the auto-formation of paragraphs for the entire template. To preserve new lines over just a section of the template, use the {{ PreserveNewLines }} template function.
func WithWidth ¶
func WithWidth(w int) ConfigOption
WithWidth sets the maximum width at which lines are word-wrapped.
type Formatter ¶
type Formatter struct {
// contains filtered or unexported fields
}
Formatter is used to format a template such that it can be outputted to users. The formatter wraps lines and ignores any initial indentation. Further, it supplements the text/template string with functions for colorizing and styling output.
func New ¶
func New(io iostreams.IOStreams, options ...ConfigOption) *Formatter
New returns a new formatter given the IOStreams and passed options.
func (*Formatter) Doc ¶
Doc takes a text/template string and renders it. The formatter adds the following functions that are available to the template string.
- PreserveNewLines: Must be paired. Any text between the two calls will have new lines preserved.
- Color <text-color> "string"
- Color <text-color> <background-color> "string"
- Bold "string"
- Italic "string"
- Faint "string"
- Underline "string"
- Blink "string"
- CrossOut "string"
- Link "name" "url" {{ Link "
- Code "string"
- CodeBlock "string" "extension" (shell-session, json, go)
- IsMD: Returns true if the output is markdown.
Valid Color values are: "red", "green", "yellow", "orange", "gray", white", "black" (case insensitive), or "#<hex>".
These functions can be chained such as: {{ Color "Red" ( Italic (CrossOut "example" ) ) }}
Additionally, the following templates are made available:
- mdCodeOrBold: If the output is markdown, it will return the string in a code stanza. Otherwise, it will return the string in bold. An example usage is: {{ template "mdCodeOrBold" "hcp projects iam read-policy --format=json" }}
After rendering the template following manipulations are made: - The text is dedented. This allows you to use a Go string literal and not worry about the indentation. e.g. ` your docs`. -> `your docs` - Long lines are wrapped at word boundaries. The default wrapping length can be overridden using WithWidth. - Starting and ending blank spaces are stripped.
func (*Formatter) Docf ¶
Docf takes a text/template string and a series of arguments that are fmt.Sprintf into the template before the interpolatted string is passed to Doc function. To see the format of the tmpl, see Doc's documentation.
Source Files