github.com/hashicorp/hcl/v2@v2.20.0/guide/go_parsing.rst (about)

     1  .. _go-parsing:
     2  
     3  Parsing HCL Input
     4  =================
     5  
     6  The first step in processing HCL input provided by a user is to parse it.
     7  Parsing turns the raw bytes from an input file into a higher-level
     8  representation of the arguments and blocks, ready to be *decoded* into an
     9  application-specific form.
    10  
    11  The main entry point into HCL parsing is :go:pkg:`hclparse`, which provides
    12  :go:type:`hclparse.Parser`:
    13  
    14  .. code-block:: go
    15  
    16    parser := hclparse.NewParser()
    17    f, diags := parser.ParseHCLFile("server.conf")
    18  
    19  Variable ``f`` is then a pointer to an :go:type:`hcl.File`, which is an
    20  opaque abstract representation of the file, ready to be decoded.
    21  
    22  Variable ``diags`` describes any errors or warnings that were encountered
    23  during processing; HCL conventionally uses this in place of the usual ``error``
    24  return value in Go, to allow returning a mixture of multiple errors and
    25  warnings together with enough information to present good error messages to the
    26  user. We'll cover this in more detail in the next section,
    27  :ref:`go-diagnostics`.
    28  
    29  .. go:package:: hclparse
    30  
    31  Package ``hclparse``
    32  --------------------
    33  
    34  .. go:type:: Parser
    35  
    36    .. go:function:: func NewParser() *Parser
    37  
    38        Constructs a new parser object. Each parser contains a cache of files
    39        that have already been read, so repeated calls to load the same file
    40        will return the same object.
    41  
    42    .. go:function:: func (*Parser) ParseHCL(src []byte, filename string) (*hcl.File, hcl.Diagnostics)
    43  
    44       Parse the given source code as HCL native syntax, saving the result into
    45       the parser's file cache under the given filename.
    46  
    47    .. go:function:: func (*Parser) ParseHCLFile(filename string) (*hcl.File, hcl.Diagnostics)
    48  
    49       Parse the contents of the given file as HCL native syntax. This is a
    50       convenience wrapper around ParseHCL that first reads the file into memory.
    51  
    52    .. go:function:: func (*Parser) ParseJSON(src []byte, filename string) (*hcl.File, hcl.Diagnostics)
    53  
    54       Parse the given source code as JSON syntax, saving the result into
    55       the parser's file cache under the given filename.
    56  
    57    .. go:function:: func (*Parser) ParseJSONFile(filename string) (*hcl.File, hcl.Diagnostics)
    58  
    59       Parse the contents of the given file as JSON syntax. This is a
    60       convenience wrapper around ParseJSON that first reads the file into memory.
    61  
    62  The above list just highlights the main functions in this package.
    63  For full documentation, see
    64  `the hclparse godoc <https://godoc.org/github.com/hashicorp/hcl/v2/hclparse>`_.