Struct Body

Source

pub struct Body { /* private fields */ }

Expand description

Represents an HCL config file body.

A Body consists of zero or more Attribute and Block HCL structures.

Implementations§

Source §

impl Body

Source

pub fn new() -> Self

Constructs a new, empty Body.

Source

pub fn with_capacity(capacity: usize) -> Self

Constructs a new, empty Body with at least the specified capacity.

Source

pub fn builder() -> BodyBuilder

Creates a new BodyBuilder to start building a new Body.

Source

pub fn is_empty(&self) -> bool

Returns true if the body contains no structures.

Source

pub fn len(&self) -> usize

Returns the number of structures in the body, also referred to as its ‘length’.

Source

pub fn clear(&mut self)

Clears the body, removing all structures.

Source

pub fn get(&self, index: usize) -> Option<&Structure>

Returns a reference to the structure at the given index, or None if the index is out of bounds.

Source

pub fn get_mut(&mut self, index: usize) -> Option<&mut Structure>

Returns a mutable reference to the structure at the given index, or None if the index is out of bounds.

Source

pub fn has_attribute(&self, key: &str) -> bool

Returns true if the body contains an attribute with given key.

§Example

use hcl_edit::structure::{Attribute, Body};
use hcl_edit::Ident;

let body = Body::from_iter([Attribute::new(Ident::new("foo"), "bar")]);
assert!(body.has_attribute("foo"));
assert!(!body.has_attribute("bar"));

Source

pub fn has_blocks(&self, ident: &str) -> bool

Returns true if the body contains blocks with given identifier.

§Example

use hcl_edit::structure::{Block, Body};
use hcl_edit::Ident;

let body = Body::from_iter([Block::new(Ident::new("foo"))]);
assert!(body.has_blocks("foo"));
assert!(!body.has_blocks("bar"));

Source

pub fn get_attribute(&self, key: &str) -> Option<&Attribute>

Returns a reference to the Attribute with given key if it exists, otherwise None.

§Example

use hcl_edit::structure::{Attribute, Body};
use hcl_edit::Ident;

let mut body = Body::new();

assert!(body.get_attribute("foo").is_none());

let foo = Attribute::new(Ident::new("foo"), "bar");

body.push(foo.clone());

assert_eq!(body.get_attribute("foo"), Some(&foo));

Source

pub fn get_attribute_mut(&mut self, key: &str) -> Option<AttributeMut<'_>>

Returns a mutable reference to the Attribute with given key if it exists, otherwise None.

§Example

use hcl_edit::expr::Expression;
use hcl_edit::structure::{Attribute, Body};
use hcl_edit::Ident;

let mut body = Body::new();

assert!(body.get_attribute("foo").is_none());

let foo = Attribute::new(Ident::new("foo"), "bar");

body.push(foo.clone());

if let Some(mut attr) = body.get_attribute_mut("foo") {
    *attr.value_mut() = Expression::from("baz");
}

assert_eq!(body.get_attribute("foo"), Some(&Attribute::new(Ident::new("foo"), "baz")));

Source

pub fn get_blocks<'a>(&'a self, ident: &'a str) -> Blocks<'a>

Returns an iterator visiting all Blocks with the given identifier. The iterator element type is &'a Block.

§Example

use hcl_edit::structure::Body;

let input = r#"
resource "aws_s3_bucket" "bucket" {}

variable "name" {}

resource "aws_instance" "instance" {}
"#;

let body: Body = input.parse()?;

let resources: Body = body.get_blocks("resource").cloned().collect();

let expected = r#"
resource "aws_s3_bucket" "bucket" {}

resource "aws_instance" "instance" {}
"#;

assert_eq!(resources.to_string(), expected);

Source

pub fn get_blocks_mut<'a>(&'a mut self, ident: &'a str) -> BlocksMut<'a>

Returns an iterator visiting all Blocks with the given identifier. The iterator element type is &'a mut Block.

§Example

use hcl_edit::expr::{Traversal, TraversalOperator};
use hcl_edit::structure::{Attribute, Body};
use hcl_edit::Ident;

let input = r#"
resource "aws_s3_bucket" "bucket" {}

variable "name" {}

resource "aws_db_instance" "db_instance" {}
"#;

let mut body: Body = input.parse()?;

for block in body.get_blocks_mut("resource") {
    let operators = vec![TraversalOperator::GetAttr(Ident::new("name").into()).into()];
    let value = Traversal::new(Ident::new("var"), operators);
    block.body.push(Attribute::new(Ident::new("name"), value));
}

let expected = r#"
resource "aws_s3_bucket" "bucket" { name = var.name }

variable "name" {}

resource "aws_db_instance" "db_instance" { name = var.name }
"#;

assert_eq!(body.to_string(), expected);

Source

pub fn insert(&mut self, index: usize, structure: impl Into<Structure>)

Inserts a structure at position index within the body, shifting all structures after it to the right.

If it is attempted to insert an Attribute which already exists in the body, it is ignored and not inserted. For a fallible variant of this function see Body::try_insert.

§Panics

Panics if index > len.

Source

pub fn try_insert( &mut self, index: usize, structure: impl Into<Structure>, ) -> Result<(), Attribute>

Inserts a structure at position index within the body, shifting all structures after it to the right.

§Errors

If it is attempted to insert an Attribute which already exists in the body, it is not inserted and returned as the Result’s Err variant instead.

§Panics

Panics if index > len.

§Example

use hcl_edit::structure::{Attribute, Body};
use hcl_edit::Ident;

let mut body = Body::new();

body.push(Attribute::new(Ident::new("foo"), "bar"));
assert!(body.try_insert(0, Attribute::new(Ident::new("bar"), "baz")).is_ok());
assert_eq!(body.len(), 2);

let duplicate_attr = Attribute::new(Ident::new("foo"), "baz");

assert_eq!(body.try_insert(0, duplicate_attr.clone()), Err(duplicate_attr));

Source

pub fn push(&mut self, structure: impl Into<Structure>)

Appends a structure to the back of the body.

If it is attempted to append an Attribute which already exists in the body, it is ignored and not appended. For a fallible variant of this function see Body::try_push.

§Panics

Panics if the new capacity exceeds isize::MAX bytes.

Source

pub fn try_push( &mut self, structure: impl Into<Structure>, ) -> Result<(), Attribute>

Appends a structure to the back of the body.

§Errors

If it is attempted to append an Attribute which already exists in the body, it is not appended and returned as the Result’s Err variant instead.

§Panics

Panics if the new capacity exceeds isize::MAX bytes.

§Example

use hcl_edit::structure::{Attribute, Body};
use hcl_edit::Ident;

let mut body = Body::new();

assert!(body.try_push(Attribute::new(Ident::new("foo"), "bar")).is_ok());
assert!(body.try_push(Attribute::new(Ident::new("bar"), "baz")).is_ok());
assert_eq!(body.len(), 2);

let duplicate_attr = Attribute::new(Ident::new("foo"), "baz");

assert_eq!(body.try_push(duplicate_attr.clone()), Err(duplicate_attr));

Source

pub fn pop(&mut self) -> Option<Structure>

Removes the last structure from the body and returns it, or None if it is empty.

Source

pub fn remove(&mut self, index: usize) -> Structure

Removes and returns the structure at position index within the body, shifting all elements after it to the left.

Like Vec::remove, the structure is removed by shifting all of the structures that follow it, preserving their relative order. This perturbs the index of all of those elements!

§Panics

Panics if index is out of bounds.

Source

pub fn remove_attribute(&mut self, key: &str) -> Option<Attribute>

Removes and returns the attribute with given key.

§Example

use hcl_edit::structure::{Attribute, Block, Body};
use hcl_edit::Ident;

let mut body = Body::new();
body.push(Block::new(Ident::new("block")));

assert!(body.remove_attribute("foo").is_none());

let foo = Attribute::new(Ident::new("foo"), "bar");

body.push(foo.clone());

assert_eq!(body.len(), 2);
assert_eq!(body.remove_attribute("foo"), Some(foo));
assert_eq!(body.len(), 1);

Source

pub fn remove_blocks(&mut self, ident: &str) -> Vec<Block>

Removes and returns all blocks with given ident.

§Example

use hcl_edit::structure::{Attribute, Block, Body};
use hcl_edit::Ident;

let mut body = Body::builder()
    .attribute(Attribute::new(Ident::new("foo"), "bar"))
    .block(
        Block::builder(Ident::new("resource"))
            .labels(["aws_s3_bucket", "bucket"])
    )
    .block(Block::builder(Ident::new("variable")).label("name"))
    .block(
        Block::builder(Ident::new("resource"))
            .labels(["aws_db_instance", "db_instance"])
    )
    .build();

let resources = body.remove_blocks("resource");

assert_eq!(
    resources,
    vec![
        Block::builder(Ident::new("resource"))
            .labels(["aws_s3_bucket", "bucket"])
            .build(),
        Block::builder(Ident::new("resource"))
            .labels(["aws_db_instance", "db_instance"])
            .build()
    ]
);

assert_eq!(
    body,
    Body::builder()
        .attribute(Attribute::new(Ident::new("foo"), "bar"))
        .block(Block::builder(Ident::new("variable")).label("name"))
        .build()
);

Source

pub fn iter(&self) -> Iter<'_>

An iterator visiting all body structures in insertion order. The iterator element type is &'a Structure.

Source

pub fn iter_mut(&mut self) -> IterMut<'_>

An iterator visiting all body structures in insertion order, with mutable references to the values. The iterator element type is StructureMut<'a>.

Source

pub fn into_attributes(self) -> IntoAttributes

An owning iterator visiting all Attributes within the body in insertion order. The iterator element type is Attribute.

Source

pub fn attributes(&self) -> Attributes<'_>

An iterator visiting all Attributes within the body in insertion order. The iterator element type is &'a Attribute.

Source

pub fn attributes_mut(&mut self) -> AttributesMut<'_>

An iterator visiting all Attributes within the body in insertion order, with mutable references to the values. The iterator element type is AttributeMut<'a>.

Source

pub fn into_blocks(self) -> IntoBlocks

An owning iterator visiting all Blocks within the body in insertion order. The iterator element type is Block.

Source

pub fn blocks(&self) -> Blocks<'_>

An iterator visiting all Blocks within the body in insertion order. The iterator element type is &'a Block.

Source

pub fn blocks_mut(&mut self) -> BlocksMut<'_>

An iterator visiting all Blocks within the body in insertion order, with mutable references to the values. The iterator element type is &'a mut Block.

Source

pub fn set_prefer_oneline(&mut self, yes: bool)

Configures whether the body should be displayed on a single line.

This is only a hint which will be applied if the Body is part of a Block (that is: not the document root) and only if either of these conditions meet:

The body is empty. In this case, the opening ({) and closing (}) braces will be places on the same line.
The body only consist of a single Attribute, which will be placed on the same line as the opening and closing braces.

In all other cases this hint is ignored.

Source