.DART File Format – File structure

Encoding

The specification describes source text as a sequence of Unicode code points. The Dart tools read files as UTF-8 bytes. A UTF-8 byte order mark (EF BB BF) may come first and is skipped by the scanner, and the SDK’s grammar allows it before the script tag in a library and before the header in a part.

A line ends with a carriage return, a line feed, or a carriage return followed by a line feed. Line endings do not otherwise matter, because statements end with semicolons.

Order of a file

The parts of a library always come in this order (spec: Libraries and Scripts):

libraryDeclaration ::= scriptTag? libraryName?
                       importOrExport*
                       partDirective*
                       (metadata topLevelDeclaration)*
                       EOF

Directives and declarations can have metadata (annotations) before them. Comments can appear anywhere between tokens, and the language version comment may have other comments above it.

#!/usr/bin/env dart
// Copyright notice: any comments may come first.
// @dart = 3.10

/// Tools for greeting people.
library;

import 'dart:io';

import 'package:path/path.dart' as p;

export 'src/greeting.dart' show Greeting;

part 'greet_helpers.dart';

const greeting = 'Hello';

void main(List<String> args) {
  stdout.writeln('$greeting from ${p.basename(Platform.script.path)}');
}

Script tag

A file may begin with #! and the rest of that line, which Unix systems read to find the interpreter. Dart ignores it. The lexical rule is '#!' (~('\r' | '\n'))* NEWLINE.

Language version comment

A package’s default language version is the lower bound of the sdk constraint in its pubspec.yaml. A library can select a different version with a comment of this form:

// @dart = 3.10

• It must be a // comment, not /// or /*.
• It must come before any Dart code. Other comments may come before it.
• Spaces and tabs do not matter, except inside the @dart and version strings.
• The version has a major and a minor number only. An SDK supports its own language version and earlier ones in the same major version, so a version before 2.12 is not available in Dart 3.

Library directive

Every Dart file, with its parts, is a library even without a library directive. The directive is needed only to attach a documentation comment or annotations to the library as a whole.

Since language version 2.19 the directive can have no name: library;. The older named form, library my.tools;, is still valid, and the Dart style guide advises against naming libraries.

/// A really great test library.
@TestOn('browser')
library;

Part files

A part directive pulls another file into the library. That file must begin with a part of header that names the library by URI or by name, and it then holds only declarations. It cannot have imports or parts of its own (spec: Parts). A library may not list the same URI in two part directives.

// greet_helpers.dart
part of 'main.dart';

String shout(String text) => text.toUpperCase();

The Dart team recommends small libraries instead of parts.

Top-level declarations

Functions and variables can sit directly in a file. The kinds of top-level declaration are:

A library’s declarations share one namespace, and two may not have the same name, except a getter and setter pair. Names that begin with an underscore are private to the library.

The main function

A program starts at a top-level function named main. The specification calls a library that exports such a function a script. main has zero, one or two required positional parameters:

main can be async, returning a Future, when it needs await.

File names

The extension is .dart. The Dart style guide asks for names in lowercase_with_underscores, so that they work on case-insensitive file systems and stay valid identifiers. Test files under test/ end in _test.dart.

Comments read by tools

Some ordinary comments carry instructions for the SDK’s tools. The language ignores them.

Formatting

The language does not restrict white space, but dart format gives Dart code one standard form. Its default line length is 80 characters. Width and trailing-comma settings can go in a formatter section of analysis_options.yaml, which needs language version 3.7 or later, and trailing_commas needs 3.8. The formatter’s output depends on the language version: files at 3.7 or later get the “tall” style.

What a file becomes

Source files run directly with dart run, or dart compile turns them into one of these: