Struct Formatter

pub struct Formatter<'a, W> {
    buf: FormatBuffer<W>,
    source: &'a str,
    config: FormatterConfig,
    temp_bufs: Vec<FormatBuffer<String>>,
    context: Context,
    comments: Comments,
    inline_config: InlineConfig,
}

A Solidity formatter

Fields

buf: FormatBuffer<W>

source: &'a str

config: FormatterConfig

temp_bufs: Vec<FormatBuffer<String>>

context: Context

comments: Comments

inline_config: InlineConfig

Implementations

impl<'a, W: Write> Formatter<'a, W>

pub fn new( w: W, source: &'a str, comments: Comments, inline_config: InlineConfig, config: FormatterConfig, ) -> Self

fn buf(&mut self) -> &mut dyn Write

Get the Write interface of the current temp buffer or the underlying Write

unsafe fn buf_contents(&self) -> &String

Casts the current writer w as a String reference. Should only be used for debugging.

unsafe fn temp_buf_contents(&self) -> &String

Casts the current W writer or the current temp buffer as a String reference. Should only be used for debugging.

fn indent(&mut self, delta: usize)

fn dedent(&mut self, delta: usize)

fn start_group(&mut self)

fn end_group(&mut self)

fn create_temp_buf(&self) -> FormatBuffer<String>

fn restrict_to_single_line(&mut self, restricted: bool)

fn current_line_len(&self) -> usize

fn total_indent_len(&self) -> usize

fn is_beginning_of_line(&self) -> bool

fn last_char(&self) -> Option<char>

fn last_indent_group_skipped(&self) -> bool

fn set_last_indent_group_skipped(&mut self, skip: bool)

fn write_raw(&mut self, s: impl AsRef<str>) -> Result

fn with_temp_buf( &mut self, fun: impl FnMut(&mut Self) -> Result<(), FormatterError>, ) -> Result<FormatBuffer<String>, FormatterError>

Do the callback within the context of a temp buffer

fn next_char_needs_space(&self, next_char: char) -> bool

Does the next written character require whitespace before

fn will_it_fit(&self, text: impl AsRef<str>) -> bool

Is length of the text with respect to already written line <= config.line_length

fn write_empty_brackets(&mut self) -> Result<(), FormatterError>

Write empty brackets with respect to config.bracket_spacing setting: "{ }" if true, "{}" if false

fn write_semicolon(&mut self) -> Result<(), FormatterError>

Write semicolon to the buffer

fn write_whitespace_separator( &mut self, multiline: bool, ) -> Result<(), FormatterError>

Write whitespace separator to the buffer "\n" if multiline is true, " " if false

fn write_preserved_line(&mut self) -> Result<(), FormatterError>

Write new line with preserved last_indent_group_skipped flag

fn write_raw_src(&mut self, loc: Loc) -> Result<(), FormatterError>

Write unformatted src and comments for given location.

fn blank_lines(&self, start: usize, end: usize) -> usize

Returns number of blank lines in source between two byte indexes

fn find_next_line(&self, byte_offset: usize) -> Option<usize>

Get the byte offset of the next line

fn find_next_in_src(&self, byte_offset: usize, needle: char) -> Option<usize>

Find the next instance of the character in source excluding comments

fn find_next_str_in_src( &self, byte_offset: usize, needle: &str, ) -> Option<usize>

Find the start of the next instance of a slice in source

fn extend_loc_until(&self, loc: &mut Loc, needle: char) -> bool

Extends the location to the next instance of a character. Returns true if the loc was extended

fn should_attempt_block_single_line( &mut self, stmt: &mut Statement, start_from: usize, ) -> bool

Return the flag whether the attempt should be made to write the block on a single line. If the block style is configured to SingleLineBlockStyle::Preserve, lookup whether there was a newline introduced in [start_from, end_at] range where end_at is the start of the block.

fn chunk_at( &mut self, byte_offset: usize, next_byte_offset: Option<usize>, needs_space: Option<bool>, content: impl Display, ) -> Chunk

Create a chunk given a string and the location information

fn chunked( &mut self, byte_offset: usize, next_byte_offset: Option<usize>, fun: impl FnMut(&mut Self) -> Result<(), FormatterError>, ) -> Result<Chunk, FormatterError>

Create a chunk given a callback

fn chunked_mono( &mut self, byte_offset: usize, next_byte_offset: Option<usize>, fun: &mut dyn FnMut(&mut Self) -> Result<(), FormatterError>, ) -> Result<Chunk, FormatterError>

fn visit_to_chunk( &mut self, byte_offset: usize, next_byte_offset: Option<usize>, visitable: &mut impl Visitable, ) -> Result<Chunk, FormatterError>

Create a chunk given a Visitable item

fn items_to_chunks<'b>( &mut self, next_byte_offset: Option<usize>, items: impl Iterator<Item = (Loc, &'b mut (impl Visitable + 'b))> + 'b, ) -> Result<Vec<Chunk>, FormatterError>

Transform Visitable items to the list of chunks

fn items_to_chunks_sorted<'b>( &mut self, next_byte_offset: Option<usize>, items: impl Iterator<Item = &'b mut (impl Visitable + CodeLocation + Ord + 'b)> + 'b, ) -> Result<Vec<Chunk>, FormatterError>

Transform Visitable items to a list of chunks and then sort those chunks.

fn write_comment( &mut self, comment: &CommentWithMetadata, is_first: bool, ) -> Result<(), FormatterError>

Write a comment to the buffer formatted. WARNING: This may introduce a newline if the comment is a Line comment or if the comment are wrapped

fn write_prefix_comment( &mut self, comment: &CommentWithMetadata, is_first: bool, ) -> Result<(), FormatterError>

Write a comment with position CommentPosition::Prefix

fn write_postfix_comment( &mut self, comment: &CommentWithMetadata, ) -> Result<(), FormatterError>

Write a comment with position CommentPosition::Postfix

fn write_doc_block_line( &mut self, comment: &CommentWithMetadata, line: &str, ) -> Result<(), FormatterError>

Write the line of a doc block comment line

fn write_comment_line( &mut self, comment: &CommentWithMetadata, line: &str, ) -> Result<bool, FormatterError>

Write a comment line that might potentially overflow the maximum line length and, if configured, will be wrapped to the next line.

fn write_raw_comment( &mut self, comment: &CommentWithMetadata, ) -> Result<(), FormatterError>

Write a raw comment. This is like write_comment but won’t do any formatting or worry about whitespace behind the comment.

fn write_comments<'b>( &mut self, comments: impl IntoIterator<Item = &'b CommentWithMetadata>, ) -> Result<(), FormatterError>

Write multiple comments

fn write_postfix_comments_before( &mut self, byte_end: usize, ) -> Result<(), FormatterError>

Write a postfix comments before a given location

fn write_prefix_comments_before( &mut self, byte_end: usize, ) -> Result<(), FormatterError>

Write all prefix comments before a given location

fn will_chunk_fit( &mut self, format_string: &str, chunk: &Chunk, ) -> Result<bool, FormatterError>

Check if a chunk will fit on the current line

fn are_chunks_separated_multiline<'b>( &mut self, format_string: &str, items: impl IntoIterator<Item = &'b Chunk>, separator: &str, ) -> Result<bool, FormatterError>

Check if a separated list of chunks will fit on the current line

fn write_chunk(&mut self, chunk: &Chunk) -> Result<(), FormatterError>

Write the chunk and any surrounding comments into the buffer This will automatically add whitespace before the chunk given the rule set in next_char_needs_space. If the chunk does not fit on the current line it will be put on to the next line

fn write_chunks_separated<'b>( &mut self, chunks: impl IntoIterator<Item = &'b Chunk>, separator: &str, multiline: bool, ) -> Result<(), FormatterError>

Write chunks separated by a separator. If multiline, each chunk will be written to a separate line

fn indented( &mut self, delta: usize, fun: impl FnMut(&mut Self) -> Result<(), FormatterError>, ) -> Result<(), FormatterError>

Apply the callback indented by the indent size

fn indented_if( &mut self, condition: bool, delta: usize, fun: impl FnMut(&mut Self) -> Result<(), FormatterError>, ) -> Result<(), FormatterError>

Apply the callback indented by the indent size if the condition is true

fn grouped( &mut self, fun: impl FnMut(&mut Self) -> Result<(), FormatterError>, ) -> Result<bool, FormatterError>

Apply the callback into an indent group. The first line of the indent group is not indented but lines thereafter are

fn with_function_context( &mut self, context: FunctionDefinition, fun: impl FnMut(&mut Self) -> Result<(), FormatterError>, ) -> Result<(), FormatterError>

Add a function context around a procedure and revert the context at the end of the procedure regardless of the response

fn with_contract_context( &mut self, context: ContractDefinition, fun: impl FnMut(&mut Self) -> Result<(), FormatterError>, ) -> Result<(), FormatterError>

Add a contract context around a procedure and revert the context at the end of the procedure regardless of the response

fn transact<'b>( &'b mut self, fun: impl FnMut(&mut Self) -> Result<(), FormatterError>, ) -> Result<Transaction<'b, 'a, W>, FormatterError>

Create a transaction. The result of the transaction is not applied to the buffer unless Transacton::commit is called

fn simulate_to_string( &mut self, fun: impl FnMut(&mut Self) -> Result<(), FormatterError>, ) -> Result<String, FormatterError>

Do the callback and return the result on the buffer as a string

fn chunk_to_string(&mut self, chunk: &Chunk) -> Result<String, FormatterError>

Turn a chunk and its surrounding comments into a string

fn simulate_to_single_line( &mut self, fun: impl FnMut(&mut Self) -> Result<(), FormatterError>, ) -> Result<Option<String>, FormatterError>

Try to create a string based on a callback. If the string does not fit on a single line this will return None

fn try_on_single_line( &mut self, fun: impl FnMut(&mut Self) -> Result<(), FormatterError>, ) -> Result<bool, FormatterError>

Try to apply a callback to a single line. If the callback cannot be applied to a single line the callback will not be applied to the buffer and false will be returned. Otherwise true will be returned

fn surrounded( &mut self, first: SurroundingChunk, last: SurroundingChunk, fun: impl FnMut(&mut Self, bool) -> Result<(), FormatterError>, ) -> Result<(), FormatterError>

Surrounds a callback with parentheses. The callback will try to be applied to a single line. If the callback cannot be applied to a single line the callback will applied to the nextline indented. The callback receives a multiline hint as the second argument which receives true in the latter case

fn write_lined_visitable<'b, I, V, F>( &mut self, loc: Loc, items: I, needs_space_fn: F, ) -> Result<(), FormatterError>

where I: Iterator<Item = &'b mut V> + 'b, V: Visitable + CodeLocation + 'b, F: Fn(&V, &V) -> bool,

Write each Visitable item on a separate line. The function will check if there are any blank lines between each visitable statement and will apply a single blank line if there exists any. The needs_space callback can force a newline and is given the last_item if any and the next item as arguments

fn visit_assignment( &mut self, expr: &mut Expression, ) -> Result<(), FormatterError>

Visit the right side of an assignment. The function will try to write the assignment on a single line or indented on the next line. If it can’t do this it resorts to letting the expression decide how to split itself on multiple lines

fn visit_list<T>( &mut self, prefix: &str, items: &mut [T], start_offset: Option<usize>, end_offset: Option<usize>, paren_required: bool, ) -> Result<(), FormatterError>

where T: Visitable + CodeLocation,

Visit the list of comma separated items. If the prefix is not empty, then the function will write the whitespace before the parentheses (if they are required).

fn visit_block<T>( &mut self, loc: Loc, statements: &mut [T], attempt_single_line: bool, attempt_omit_braces: bool, ) -> Result<bool, FormatterError>

where T: Visitable + CodeLocation,

Visit the block item. Attempt to write it on the single line if requested. Surround by curly braces and indent each line otherwise. Returns true if the block fit on a single line

fn visit_stmt_as_block( &mut self, stmt: &mut Statement, attempt_single_line: bool, ) -> Result<bool, FormatterError>

Visit statement as Statement::Block.

fn visit_member_access<'b, T, M>( &mut self, expr: &'b mut Box<T>, ident: &mut Identifier, matcher: M, ) -> Result<(), FormatterError>

where T: CodeLocation + Visitable, M: FnMut(&mut Self, &'b mut Box<T>) -> Result<Option<(&'b mut Box<T>, &'b mut Identifier)>, FormatterError>,

Visit the generic member access expression and attempt flatten it by checking if the inner expression matches a given member access variant.

fn visit_yul_string_with_ident( &mut self, loc: Loc, val: &str, ident: &mut Option<Identifier>, ) -> Result<(), FormatterError>

Visit the yul string with an optional identifier. If the identifier is present, write the value in the format <val>:<ident>.

Ref: https://docs.soliditylang.org/en/v0.8.15/yul.html#variable-declarations

fn quote_str(&self, loc: Loc, prefix: Option<&str>, string: &str) -> String

Format a quoted string as prefix"string" where the quote character is handled by the configuration quote_style

fn write_quoted_str( &mut self, loc: Loc, prefix: Option<&str>, string: &str, ) -> Result<(), FormatterError>

Write a quoted string. See Formatter::quote_str for more information

fn write_num_literal( &mut self, loc: Loc, value: &str, fractional: Option<&str>, exponent: &str, unit: &mut Option<Identifier>, ) -> Result<(), FormatterError>

Write and format numbers. This will fix underscores as well as remove unnecessary 0’s and exponents

fn write_hex_literal(&mut self, lit: &HexLiteral) -> Result<(), FormatterError>

Write and hex literals according to the configuration.

fn write_unit( &mut self, unit: &mut Option<Identifier>, ) -> Result<(), FormatterError>

Write built-in unit.

fn write_function_header( &mut self, func: &mut FunctionDefinition, body_loc: Option<Loc>, header_multiline: bool, ) -> Result<bool, FormatterError>

Write the function header

fn write_if_stmt( &mut self, loc: Loc, cond: &mut Expression, if_branch: &mut Box<Statement>, else_branch: &mut Option<Box<Statement>>, ) -> Result<(), FormatterError>

Write potentially nested if statements

fn sort_imports(&self, source_unit: &mut SourceUnit)

Sorts grouped import statement alphabetically.

Trait Implementations

impl<'a, W: Debug> Debug for Formatter<'a, W>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<W: Write> Visitor for Formatter<'_, W>

type Error = FormatterError

fn visit_source(&mut self, loc: Loc) -> Result<(), FormatterError>

fn visit_source_unit( &mut self, source_unit: &mut SourceUnit, ) -> Result<(), FormatterError>

fn visit_contract( &mut self, contract: &mut ContractDefinition, ) -> Result<(), FormatterError>

fn visit_annotation( &mut self, annotation: &mut Annotation, ) -> Result<(), FormatterError>

fn visit_pragma( &mut self, loc: Loc, ident: &mut Option<Identifier>, string: &mut Option<StringLiteral>, ) -> Result<(), FormatterError>

fn visit_import_plain( &mut self, loc: Loc, import: &mut ImportPath, ) -> Result<(), FormatterError>

fn visit_import_global( &mut self, loc: Loc, global: &mut ImportPath, alias: &mut Identifier, ) -> Result<(), FormatterError>

fn visit_import_renames( &mut self, loc: Loc, imports: &mut [(Identifier, Option<Identifier>)], from: &mut ImportPath, ) -> Result<(), FormatterError>

fn visit_enum( &mut self, enumeration: &mut EnumDefinition, ) -> Result<(), FormatterError>

fn visit_assembly( &mut self, loc: Loc, dialect: &mut Option<StringLiteral>, block: &mut YulBlock, flags: &mut Option<Vec<StringLiteral>>, ) -> Result<(), Self::Error>

fn visit_block( &mut self, loc: Loc, unchecked: bool, statements: &mut Vec<Statement>, ) -> Result<(), FormatterError>

fn visit_args( &mut self, loc: Loc, args: &mut Vec<NamedArgument>, ) -> Result<(), Self::Error>

fn visit_expr( &mut self, loc: Loc, expr: &mut Expression, ) -> Result<(), FormatterError>

Don’t write semicolon at the end because expressions can appear as both part of other node and a statement in the function body

fn visit_ident( &mut self, loc: Loc, ident: &mut Identifier, ) -> Result<(), FormatterError>

fn visit_ident_path( &mut self, idents: &mut IdentifierPath, ) -> Result<(), Self::Error>

fn visit_emit( &mut self, loc: Loc, event: &mut Expression, ) -> Result<(), FormatterError>

fn visit_var_definition( &mut self, var: &mut VariableDefinition, ) -> Result<(), FormatterError>

fn visit_var_definition_stmt( &mut self, loc: Loc, declaration: &mut VariableDeclaration, expr: &mut Option<Expression>, ) -> Result<(), FormatterError>

fn visit_var_declaration( &mut self, var: &mut VariableDeclaration, ) -> Result<(), FormatterError>

fn visit_return( &mut self, loc: Loc, expr: &mut Option<Expression>, ) -> Result<(), Self::Error>

fn visit_revert( &mut self, loc: Loc, error: &mut Option<IdentifierPath>, args: &mut Vec<Expression>, ) -> Result<(), Self::Error>

fn visit_revert_named_args( &mut self, loc: Loc, error: &mut Option<IdentifierPath>, args: &mut Vec<NamedArgument>, ) -> Result<(), Self::Error>

fn visit_break( &mut self, loc: Loc, semicolon: bool, ) -> Result<(), FormatterError>

fn visit_continue( &mut self, loc: Loc, semicolon: bool, ) -> Result<(), FormatterError>

fn visit_try( &mut self, loc: Loc, expr: &mut Expression, returns: &mut Option<(Vec<(Loc, Option<Parameter>)>, Box<Statement>)>, clauses: &mut Vec<CatchClause>, ) -> Result<(), Self::Error>

fn visit_if( &mut self, loc: Loc, cond: &mut Expression, if_branch: &mut Box<Statement>, else_branch: &mut Option<Box<Statement>>, is_first_stmt: bool, ) -> Result<(), Self::Error>

fn visit_do_while( &mut self, loc: Loc, body: &mut Statement, cond: &mut Expression, ) -> Result<(), Self::Error>

fn visit_while( &mut self, loc: Loc, cond: &mut Expression, body: &mut Statement, ) -> Result<(), Self::Error>

fn visit_for( &mut self, loc: Loc, init: &mut Option<Box<Statement>>, cond: &mut Option<Box<Expression>>, update: &mut Option<Box<Expression>>, body: &mut Option<Box<Statement>>, ) -> Result<(), Self::Error>

fn visit_function( &mut self, func: &mut FunctionDefinition, ) -> Result<(), FormatterError>

fn visit_function_attribute( &mut self, attribute: &mut FunctionAttribute, ) -> Result<(), FormatterError>

fn visit_var_attribute( &mut self, attribute: &mut VariableAttribute, ) -> Result<(), FormatterError>

fn visit_base(&mut self, base: &mut Base) -> Result<(), FormatterError>

fn visit_parameter( &mut self, parameter: &mut Parameter, ) -> Result<(), FormatterError>

fn visit_struct( &mut self, structure: &mut StructDefinition, ) -> Result<(), FormatterError>

fn visit_event( &mut self, event: &mut EventDefinition, ) -> Result<(), FormatterError>

fn visit_event_parameter( &mut self, param: &mut EventParameter, ) -> Result<(), FormatterError>

fn visit_error( &mut self, error: &mut ErrorDefinition, ) -> Result<(), FormatterError>

fn visit_error_parameter( &mut self, param: &mut ErrorParameter, ) -> Result<(), FormatterError>

fn visit_type_definition( &mut self, def: &mut TypeDefinition, ) -> Result<(), FormatterError>

fn visit_stray_semicolon(&mut self) -> Result<(), FormatterError>

fn visit_opening_paren(&mut self) -> Result<(), FormatterError>

fn visit_closing_paren(&mut self) -> Result<(), FormatterError>

fn visit_newline(&mut self) -> Result<(), FormatterError>

fn visit_using(&mut self, using: &mut Using) -> Result<(), FormatterError>

fn visit_yul_block( &mut self, loc: Loc, statements: &mut Vec<YulStatement>, attempt_single_line: bool, ) -> Result<(), Self::Error>

fn visit_yul_expr( &mut self, expr: &mut YulExpression, ) -> Result<(), Self::Error>

fn visit_yul_assignment<T>( &mut self, loc: Loc, exprs: &mut Vec<T>, expr: &mut Option<&mut YulExpression>, ) -> Result<(), Self::Error>

where T: Visitable + CodeLocation,

fn visit_yul_for(&mut self, stmt: &mut YulFor) -> Result<(), Self::Error>

fn visit_yul_function_call( &mut self, stmt: &mut YulFunctionCall, ) -> Result<(), Self::Error>

fn visit_yul_fun_def( &mut self, stmt: &mut YulFunctionDefinition, ) -> Result<(), Self::Error>

fn visit_yul_if( &mut self, loc: Loc, expr: &mut YulExpression, block: &mut YulBlock, ) -> Result<(), Self::Error>

fn visit_yul_leave(&mut self, loc: Loc) -> Result<(), Self::Error>

fn visit_yul_switch(&mut self, stmt: &mut YulSwitch) -> Result<(), Self::Error>

fn visit_yul_var_declaration( &mut self, loc: Loc, idents: &mut Vec<YulTypedIdentifier>, expr: &mut Option<YulExpression>, ) -> Result<(), Self::Error>

fn visit_yul_typed_ident( &mut self, ident: &mut YulTypedIdentifier, ) -> Result<(), Self::Error>

fn visit_parser_error(&mut self, loc: Loc) -> Result<(), FormatterError>

Layout

Note: Unable to compute type layout, possibly due to this type having generic parameters. Layout can only be computed for concrete, fully-instantiated types.