From 245e3cee7cd50efaa470b803c7379f7defe47a4d Mon Sep 17 00:00:00 2001 From: Mark Harrah Date: Fri, 16 Aug 2013 14:21:45 -0400 Subject: [PATCH] API docs for File/NameFilters --- util/io/src/main/scala/sbt/NameFilter.scala | 46 +++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/util/io/src/main/scala/sbt/NameFilter.scala b/util/io/src/main/scala/sbt/NameFilter.scala index ef78a6652..40c93acb5 100644 --- a/util/io/src/main/scala/sbt/NameFilter.scala +++ b/util/io/src/main/scala/sbt/NameFilter.scala @@ -6,51 +6,90 @@ package sbt import java.io.File import java.util.regex.Pattern +/** A `java.io.FileFilter` with additional methods for combining filters. */ trait FileFilter extends java.io.FileFilter with NotNull { + /** Constructs a filter that accepts a `File` if it matches either this filter or the given `filter`. */ def || (filter: FileFilter): FileFilter = new SimpleFileFilter( file => accept(file) || filter.accept(file) ) + + /** Constructs a filter that accepts a `File` if it matches both this filter and the given `filter`. */ def && (filter: FileFilter): FileFilter = new SimpleFileFilter( file => accept(file) && filter.accept(file) ) + + /** Constructs a filter that accepts a `File` if it matches this filter but does not match the given `filter`. */ def -- (filter: FileFilter): FileFilter = new SimpleFileFilter( file => accept(file) && !filter.accept(file) ) + + /** Constructs a filter that accepts a `File` if it does not match this filter. */ def unary_- : FileFilter = new SimpleFileFilter( file => !accept(file) ) } + +/** A filter on Strings. This also functions as a [[FileFilter]] by applying the String filter to the value of a File's `getName`. */ trait NameFilter extends FileFilter with NotNull { + /** Returns `true` to include the `name`, `false` to exclude it. */ def accept(name: String): Boolean + + /** Accepts `File` if its `getName` method is accepted by this filter. */ final def accept(file: File): Boolean = accept(file.getName) + + /** Constructs a filter that accepts a `String` if it matches either this filter or the given `filter`. */ def | (filter: NameFilter): NameFilter = new SimpleFilter( name => accept(name) || filter.accept(name) ) + + /** Constructs a filter that accepts a `String` if it matches both this filter and the given `filter`. */ def & (filter: NameFilter): NameFilter = new SimpleFilter( name => accept(name) && filter.accept(name) ) + + /** Constructs a filter that accepts a `String` if it matches this filter but not the given `filter`. */ def - (filter: NameFilter): NameFilter = new SimpleFilter( name => accept(name) && !filter.accept(name) ) + + /** Constructs a filter that accepts a `String` if it does not match this filter. */ override def unary_- : NameFilter = new SimpleFilter( name => !accept(name) ) } + +/** A [[FileFilter]] that selects files that are hidden according to `java.io.File.isHidden` or if they start with a dot (`.`). */ object HiddenFileFilter extends FileFilter { def accept(file: File) = file.isHidden && file.getName != "." } + +/** A [[FileFilter]] that selects files that exist according to `java.io.File.exists`. */ object ExistsFileFilter extends FileFilter { def accept(file: File) = file.exists } + +/** A [[FileFilter]] that selects files that are a directory according to `java.io.File.isDirectory`. */ object DirectoryFilter extends FileFilter { def accept(file: File) = file.isDirectory } + +/** A [[FileFilter]] that selects files according the predicate `acceptFunction`. */ final class SimpleFileFilter(val acceptFunction: File => Boolean) extends FileFilter { def accept(file: File) = acceptFunction(file) } + +/** A [[NameFilter]] that accepts a name if it is exactly equal to `matchName`. */ final class ExactFilter(val matchName: String) extends NameFilter { def accept(name: String) = matchName == name } + +/** A [[NameFilter]] that accepts a name if the predicate `acceptFunction` accepts it. */ final class SimpleFilter(val acceptFunction: String => Boolean) extends NameFilter { def accept(name: String) = acceptFunction(name) } + +/** A [[NameFilter]] that accepts a name if it matches the regular expression defined by `pattern`. */ final class PatternFilter(val pattern: Pattern) extends NameFilter { def accept(name: String) = pattern.matcher(name).matches } + +/** A [[NameFilter]] that accepts all names. That is, `accept` always returns `true`. */ object AllPassFilter extends NameFilter { def accept(name: String) = true } + +/** A [[NameFilter]] that accepts nothing. That is, `accept` always returns `false`. */ object NothingFilter extends NameFilter { def accept(name: String) = false @@ -64,10 +103,17 @@ object NameFilter } object FileFilter { + /** Allows a String to be used where a `NameFilter` is expected and any asterisks (`*`) will be interpreted as wildcards. See [[sbt.GlobFilter]].*/ implicit def globFilter(s: String): NameFilter = GlobFilter(s) } + +/** Constructs a filter from a String, interpreting wildcards. See the [[apply]] method. */ object GlobFilter { + /** Constructs a [[NameFilter]] from a String, interpreting `*` as a wildcard. + * Control characters, as determined by `java.lang.Character.isISOControl` are not allowed + * due to the implementation restriction of using Java's `Pattern` and `Pattern.quote`, + * which do not handle these characters. */ def apply(expression: String): NameFilter = { require(!expression.exists(java.lang.Character.isISOControl), "Control characters not allowed in filter expression.")