clay library

Core library for Clay — config, transforms, generation, and validation.

Clay turns runnable reference projects into Mason brick templates using comment-based annotation markers in source files and a clay.yaml config file.

Reference authors mark up files with comment tokens such as /*remove-start*/, #replace-start#, or <!--partial v header-->. During generation, markers are resolved and removed from the output tree.

See the annotation reference for full marker syntax, comment flavors, and examples.

Classes

AnnotationIssue
A single annotation validation problem in a reference file.
ClayConfig
Parsed clay.yaml configuration.
ClayConfigCopyWith<$R, $In extends ClayConfig, $Out>
ClayConfigMapper
ClayEnvironment
Semver environment constraints declared in clay.yaml.
ClayEnvironmentCopyWith<$R, $In extends ClayEnvironment, $Out>
ClayEnvironmentMapper
DiscoveredClayConfig
Result of locating clay.yaml and its project root.
LineDeletion
Line ranges to drop from a specific target file.
LineDeletionCopyWith<$R, $In extends LineDeletion, $Out>
LineDeletionMapper
LineRange
An inclusive, zero-based line range within a target file.
LineRangeCopyWith<$R, $In extends LineRange, $Out>
LineRangeMapper
Replacement
A regex replacement applied to file paths and contents.
ReplacementCopyWith<$R, $In extends Replacement, $Out>
ReplacementMapper

Extensions

ClayConfigValueCopy on ObjectCopyWith<$R, ClayConfig, $Out>
ClayEnvironmentValueCopy on ObjectCopyWith<$R, ClayEnvironment, $Out>
LineDeletionValueCopy on ObjectCopyWith<$R, LineDeletion, $Out>
LineRangeValueCopy on ObjectCopyWith<$R, LineRange, $Out>
ReplacementValueCopy on ObjectCopyWith<$R, Replacement, $Out>

Constants

binaryContentBasenames → const Set<String>
Basenames copied to output without text transforms.
binaryContentExtensions → const Set<String>
File extensions copied to output without text transforms.
clayConfigFileName → const String
Filename for the Clay project config at the project root.
clayCoreVersion → const String
The Clay core library version.

Functions

assertClayCompatible(ClayConfig config) → void
Throws ClayIncompatibleException when config is not compatible with Clay.
assertPreviewPathIsFile(String resolvedFilePath, {FileSystemEntityType resolveEntityType(String path)?}) → void
Throws when resolvedFilePath does not refer to a readable file.
collectClayConfigSearchPaths({required String startDir}) → List<String>
Collects candidate clay.yaml paths when walking up from startDir.
discoverClayConfig({String? configPath, String? cwd}) → DiscoveredClayConfig
Discovers clay.yaml using an explicit configPath or walk-up from cwd.
expandIgnorePattern(String pattern) → List<String>
Expands a gitignore-style pattern into glob patterns for matching.
generateTemplate({required ClayConfig config, required String referencePath, required String targetPath, void onIgnoredFile(String relativePath)?}) → Future<void>
Copies referencePath to targetPath and applies config transforms.
ignorePatternValidationError(String pattern) → String?
Returns an error message when pattern is invalid for ignore matching.
isClayConfigCompatibleWithClay(ClayConfig config) → bool
Returns whether config is compatible with the current Clay library version.
loadClayConfig({required String configPath, ClayConfig parseConfigMapForTesting(Map<String, dynamic> map)?}) → Future<ClayConfig>
Loads and parses clay.yaml from configPath.
loadPreviewPartials(Directory targetDir) → Map<String, List<int>>
Loads partial files created during annotation resolution.
matchesIgnorePattern({required String relativePath, required String pattern}) → bool
Returns whether relativePath matches a single gitignore-style pattern.
matchesIgnorePatterns({required String relativePath, required List<String> patterns}) → bool
Returns whether relativePath is excluded by patterns.
parsePreviewVars(String? raw) → Map<String, dynamic>
Parses key=value pairs from a comma-separated CLI value.
previewReferenceFile({required String filePath, required String referencePath, required ClayConfig config, required bool templateOnly, Map<String, dynamic> vars = const {}}) → Future<String>
Transforms filePath under referencePath and optionally renders Mason vars.
relativePathWithinRoot({required String rootDirectory, required String absolutePath}) → String?
Returns the normalized path of absolutePath relative to rootDirectory.
resolvePathFromProjectRoot({required String projectRoot, required String path}) → String
Resolves path relative to projectRoot, or returns the normalized path when it is absolute.
resolveReferenceContent({required String content, required String targetRelativePath, required String targetAbsolutePath, required ClayConfig config}) → String
Applies the annotation and config transforms to content as if it lived at targetRelativePath under targetAbsolutePath.
resolveReferenceFilePath({required String filePath, required String referencePath}) → String
Resolves filePath to an absolute path under referencePath.
resolveReferencePath({required String projectRoot, required ClayConfig config, String? cliOverride}) → String
Resolves the reference directory path.
resolveTargetPath({required String projectRoot, required ClayConfig config, String? cliOverride}) → String
Resolves the target directory path.
shouldIgnoreAtRoot({required String rootDirectory, required String absolutePath, required List<String> patterns}) → bool
Returns whether absolutePath under rootDirectory is excluded by patterns.
shouldSkipBinaryContent(String path) → bool
Whether path should bypass the annotation transform pipeline.
validateAnnotations({required Directory referenceDir}) → List<AnnotationIssue>
Recursively validates annotation markers under referenceDir.
validateIgnorePatterns(List<String> patterns) → void
Validates patterns for ignore matching.

Exceptions / Errors

ClayConfigException
Thrown when clay.yaml cannot be loaded or parsed.
ClayConfigNotFoundException
Thrown when clay.yaml cannot be discovered.
ClayIncompatibleException
Thrown when the running Clay version does not satisfy environment.clay.
GenerationException
Thrown when template generation cannot proceed.
PreviewException
Thrown when preview cannot proceed.
ValidationException
Thrown when annotation validation cannot proceed.