// Copyright (c) HashiCorp, Inc.
// SPDX-License-Identifier: BUSL-1.1

// The protohcl package aims to define a canonical way to translate between
// protobuf and HCL encodings of data.
//
// Similar to google.golang.org/protobuf/encoding/protojson it intends to be
// opinionated about what the canonical HCL representation of a protobuf type
// should be.
//
// As HCL is a user centric data format as opposed to JSON/Protobuf which
// are intended to be used more by machines, efficiency is not a primary goal
// of this package as it is expected that users are either doing the encoding to and
// decoding from HCL at the edge (such as within the Consul CLI) or that even
// when done on servers, the rate that servers perform these translations should
// be low enough to have any inefficiency produce a tangible performance impact.
//
// HCL has two different syntaxes that could be used to represent data: attribute and block
//
// This implementation chooses to represent primitive values, enums and the well known wrapper types and
// collections of these values (maps and repeated fields) with attribute syntax. Other messages and collections
// with message value types will be represented with block syntax for example
//
// message Foo {
//    map<string, int32> map_of_ints = 1;
//	   map<string, OtherMessage> map_of_messages = 2;
// }
//
// would have HCL like:
//
// map_of_ints = {
//    "foo": 1,
//    "bar": 2,
// }
// map_of_messages "foo" {
//    ...other fields
// }
// map_of_messages "bar" {
//    ...other fields
// }
//
// Similar goes for list of primitives vs list of messages (except the block syntax uses no labels). The differences
// between primitive fields outside of a collection and a message field really just amounts to not having to specify
// the "=" between the field name and the "{" character.
//
// Field Mapping
// | proto3                 | HCL Type      | example | notes                                                                           |
// |------------------------+---------------+---------+---------------------------------------------------------------------------------+
// | message                | Object        |         | Represented as a block                                                          |
// | enum                   | String        |         |                                                                                 |
// | map<K,V>               | Map           |         | All keys are converted to/from strings.                                         |
// | repeated V             | List          |         |                                                                                 |
// | bool                   | Bool          |         |                                                                                 |
// | string                 | String        |         |                                                                                 |
// | bytes                  | base64 String |         |                                                                                 |
// | int32, fixed32, uint32 | Number        |         |                                                                                 |
// | int64, fixed64, uint64 | Number        |         |                                                                                 |
// | float, double          | Number        |         |                                                                                 |
//
// ----- Well Known Types -----
//
// | Any                    | Object        |         |                                                                                 |
// | Timestamp              | String        |         | RFC 3339 compliant                                                              |
// | Duration               | String        |         | String form is what would be accepted by time.ParseDuration                     |
// | Struct                 | Map           |         |                                                                                 |
// | Empty                  | Object        |         | An object with no fields                                                        |
// | BoolValue              | Bool          |         | Mostly the same as a regular bool except null values in the HCL are preserved   |
// | BytesValue             | Bytes         |         | Mostly the same as a regular bytes except null values in the HCL are preserved  |
// | StringValue            | String        |         | Mostly the same as a regular string except null values in the HCL are preserved |
// | FloatValue             | Number        |         | Mostly the same as a regular float except null values in the HCL are preserved  |
// | DoubleValue            | Number        |         | Mostly the same as a regular double except null values in the HCL are preserved |
// | Int32Value             | Number        |         | Mostly the same as a regular int32 except null values in the HCL are preserved  |
// | UInt32Value            | Number        |         | Mostly the same as a regular uint32 except null values in the HCL are preserved |
// | Int64Value             | Number        |         | Mostly the same as a regular int64 except null values in the HCL are preserved  |
// | UInt64Value            | Number        |         | Mostly the same as a regular uint64 except null values in the HCL are preserved |
// | FieldMask              | String        |         | Each string of the FieldMask will be joined with a '.'                          |
//

package protohcl