65 lines
2.4 KiB
ReStructuredText
65 lines
2.4 KiB
ReStructuredText
.. _go-parsing:
|
|
|
|
Parsing HCL Input
|
|
=================
|
|
|
|
The first step in processing HCL input provided by a user is to parse it.
|
|
Parsing turns the raw bytes from an input file into a higher-level
|
|
representation of the arguments and blocks, ready to be *decoded* into an
|
|
application-specific form.
|
|
|
|
The main entry point into HCL parsing is :go:pkg:`hclparse`, which provides
|
|
:go:type:`hclparse.Parser`:
|
|
|
|
.. code-block:: go
|
|
|
|
parser := hclparse.NewParser()
|
|
f, diags := parser.ParseHCLFile("server.conf")
|
|
|
|
Variable ``f`` is then a pointer to an :go:type:`hcl.File`, which is an
|
|
opaque abstract representation of the file, ready to be decoded.
|
|
|
|
Variable ``diags`` describes any errors or warnings that were encountered
|
|
during processing; HCL conventionally uses this in place of the usual ``error``
|
|
return value in Go, to allow returning a mixture of multiple errors and
|
|
warnings together with enough information to present good error messages to the
|
|
user. We'll cover this in more detail in the next section,
|
|
:ref:`go-diagnostics`.
|
|
|
|
.. go:package:: hclparse
|
|
|
|
Package ``hclparse``
|
|
--------------------
|
|
|
|
.. go:type:: Parser
|
|
|
|
.. go:function:: func NewParser() *Parser
|
|
|
|
Constructs a new parser object. Each parser contains a cache of files
|
|
that have already been read, so repeated calls to load the same file
|
|
will return the same object.
|
|
|
|
.. go:function:: func (*Parser) ParseHCL(src []byte, filename string) (*hcl.File, hcl.Diagnostics)
|
|
|
|
Parse the given source code as HCL native syntax, saving the result into
|
|
the parser's file cache under the given filename.
|
|
|
|
.. go:function:: func (*Parser) ParseHCLFile(filename string) (*hcl.File, hcl.Diagnostics)
|
|
|
|
Parse the contents of the given file as HCL native syntax. This is a
|
|
convenience wrapper around ParseHCL that first reads the file into memory.
|
|
|
|
.. go:function:: func (*Parser) ParseJSON(src []byte, filename string) (*hcl.File, hcl.Diagnostics)
|
|
|
|
Parse the given source code as JSON syntax, saving the result into
|
|
the parser's file cache under the given filename.
|
|
|
|
.. go:function:: func (*Parser) ParseJSONFile(filename string) (*hcl.File, hcl.Diagnostics)
|
|
|
|
Parse the contents of the given file as JSON syntax. This is a
|
|
convenience wrapper around ParseJSON that first reads the file into memory.
|
|
|
|
The above list just highlights the main functions in this package.
|
|
For full documentation, see
|
|
`the hclparse godoc <https://godoc.org/github.com/hashicorp/hcl/v2/hclparse>`_.
|