cloth – Base Buildcloth Layer

cloth holds the core Buildcloth functions that generate output, and handle the internal representation of the build file output.

class cloth.BuildCloth(buildfile=None)

The primary base class for a generated build system file. Contains an interface for producing output, as well as the structure for representing build system fragments internally.

BuildCloth have a notion of block, or sections of a makefile, identified by keys in the builder dictionary. All items are always added to the _all key, which is the default block, but you can optionally add data to other blocks if you want to insert build specifications out of order. Nevertheless, BuildCloth is not thread-safe.

_add_to_builder(data, block, raw=False)

Internal interface used to append content to a block, used by all other methods to modify the content of a buildfile. Do not call directly: use raw() to add content directly.

May raise MalformedContent() in cases when a user attempts to add non-string data to the build file.

block(block, cloth=[])

Parameters:

• block (string) – The name of a build file block to create.
• cloth (list) – Optional; defaults to an empty block. The content of a build cloth block to insert.

Raises a DuplicateBlock error if the block exists, otherwise creates a new empty block, or a block containing the content of the cloth value.

builder = None

The main mapping of block names to block content, which are lists of lines of build systems. The _all key stores all block content, somewhat redundantly.

buildfile = None

An alias to the _all block of builder.

comment(comment, block='_all')

Parameters:

• comment (string) – The text of a comment.
• block (string) – Optional; defaults to _all. Specify the name of the block in builder.

Adds an item to a block that consists of a blank line, a single octothorpe and the text of the comment. Use comments to increase readability and explictness of the build system.

get_block(block='_all')

Parameters:block (string) – The name of a block in builder.

Returns the content of the block in builder specified by block. Used for testing and integration with other Python code.

If block does not exist in builder, get_block() raises InvalidBuilder.

newline(n=1, block='_all')

Parameters:

• n (int) – Defaults to 1.
• block (string) – Optional; defaults to _all. Specify the name of the block in builder.

Appends new empty strings to a block, which the output methods render as blank lines.

print_block(block='_all')

Parameters:block (string) – The name of a block in builder.

Prints a single named block. use for testing and writing block content to standard output.

If block does not exist in builder, print_block() raises MissingBlock.

print_content(block_order=['_all'])

Parameters:block_order (list) – Defaults to ['_all']. Must be a list. Specifies the list of order to return blocks in.

Print blocks in builder, in the order specified by block_order. Use for testing or output to standard output.

Use write() to write content to

raw(lines, block='_all')

Parameters:

• lines (list) – A list of strings used as lines inserted directly to buildfile blocks.
• block (string) – Optional; defaults to _all. Specify the name of the block in builder.

Adds raw content to the buildfile representation, useful for inserting build systems constructs not present in Buildcloth such as ifdef statements in Makefiles.

Raises MalformedRawContent if you attempt to add non-list content or a list that contains lists or dicts.

section_break(name, block='_all')

Parameters:

• name (string) – The name of the section.
• block (string) – Optional; defaults to _all. Specify the name of the block in builder.

Adds an item to a block that consists of 2 blank lines a series of octothorpe characters (e.g. #), the name and more octothrope characters. Use section breaks to increase the readability of output build systems.

write(filename, block_order=['_all'])

Parameters:

• filename (string) – The path of a file to write builder builder content to.
• block_order (list) – Defaults to ['_all']. Must be a list. Specifies the list of order to return blocks in.

Uses write_file(). In default operation, write() write_block() have the same output. write() makes it possible to write a sequence of blocks.

write_block(filename, block='_all')

Parameters:

• filename (string) – The path of a file to write builder content to.
• block (string) – The name of a builder block.

Uses write_file(). In default operation, write() write_block() have the same output. write_block() makes it possible to write a single block.

cloth.print_output(list)

Parameters:list (list) – A list of strings to print.

Takes a list as a single argument and prints each line.

cloth.write_file(list, filename)

Parameters:

• list (list) – A list of strings to write.
• filename (string) – The name of the file to write with list.

Write all items in list to the file specified by filename. Creates enclosing directories if needed, and overwrite an existing file of the same name if it exists.