Filter Rules

Path: /src/helper/filter.coffee compiled to /lib/helper/filter.js

The filter is used to select some of the files based on specific settings. You can’t call the filter directly but it is used from most methods for file selection.

Options

The filter definition is given as options array which may have some of the following specification settings. But some methods may have special additional options not mentioned here.

The filter is given as filter element in the options object and be specified as subobject or list of objects with these settings:

  • include - Array<String|RegExp>|String|RegExp to specify a inclusion pattern
  • exclude - Array<String|RegExp>|String|RegExp to specify an exclusion pattern
  • mindepth - Integer minimal depth to match
  • maxdepth - Integer maximal depth to match
  • dereference - Boolean set to true to follow symbolic links
  • type - String the inode type it should be one of:
    • file, f
    • directory, dir, d
    • link, l
    • fifo, pipe, p
    • socket, s
  • minsize - Integer|String minimal filesize
  • maxsize - Integer|String maximal filesize
  • user - Integer|String owner name or id
  • group - Integer|String owner group name or id
  • accessedAfter - Integer|String last access time should be after that value
  • accessedBefore - Integer|String last access time should be before that value
  • modifiedAfter - Integer|String last modified time should be after that value
  • modifiedBefore - Integer|String last modified time should be before that value
  • createdAfter - Integer|String creation time should be after that value
  • createdBefore - Integer|String creation time should be before that value
  • test - Function own function to use

If you use multiple options all of them have to match the file to be valid. See the details below.

Multiple Option Sets

Multiple sets of the above rules can also be given as list of option arrays. If so all files are allowed, which match any of the given option sets.

File/Path Matching

This is based on glob expressions like used in unix systems. You may use these as the include or exclude pattern while the exclude pattern has the higher priority. All files are matched which are in the include pattern and not in the exclude pattern.

Both patterns may also be given as Array to match multiple. If multiple are given they are combined logically using OR meaning that at least one include have to match and no exclude should match.

Regular expressions

The pattern may be a regular expression given as String. SeeRegExp for the format description.

Pattern Matching

Alternatively you may use glob pattern string with the following specification:

To use one of the special characters *, ? or [ you have to preceed it with an backslash.

The patter may contain:

  • ? (not between brackets) matches any single character.
  • * (not between brackets) matches any string, including the empty string.
  • ** (not between brackets) matches any string and also includes the path separator.

Character groups:

  • [ade] or [a-z] Matches any one of the enclosed characters ranges can be given using a hyphen.
  • [!ade] or [!a-z] negates the search and matches any character not enclosed.
  • [^ade] or [^a-z] negates the search and matches any character not enclosed.

Brace Expansion:

  • {a,b} will be expanded to a or b
  • {a,b{c,d}} stacked to match a, bc or bd
  • {1..3} will be expanded to 1 or 2 or 3

Extended globbing is also possible:

  • ?(list): Matches zero or one occurrence of the given patterns.
  • *(list): Matches zero or more occurrences of the given patterns.
  • +(list): Matches one or more occurrences of the given patterns.
  • @(list): Matches one of the given patterns.

See more information about pattern matching inminimatch.

Example

CoffeeScript Code
fs = require 'alinex-fs'
fs.find '/tmp/some/directory',
  filter:
    include: 'a*'
    exclude: '*c'
, (err, list) ->
  # list may include 'a', 'abd', 'abe'
  # but not 'abc'

Search depth

The search depth specifies in which level of subdirectories the filter will match. 1 means everything in the given directory, 2 one level deeper.

  • mindepth - Integer minimal depth to match
  • maxdepth - Integer maximal depth to match

Example

CoffeeScript Code
fs = require 'alinex-fs'
fs.find '/tmp/some/directory',
  filter:
    mindepth: 1
    maxdepth: 1
, (err, list) ->
  # only the first sublevele:
  # list may include 'dir1/abc', 'dir1/abd', 'dir1/abe', 'dir1/bb', 'dir1/bcd', 'dir1/dir2'

File type

Use type to specify which type of file you want to use.

Possible values:

  • file, f
  • directory, dir, d
  • link, l
  • fifo, pipe, p
  • socket, s

Also you may set dereference to true to follow symbolic links and analyze their target.

Example

CoffeeScript Code
fs = require 'alinex-fs'
fs.find '/tmp/some/directory',
  filter:
    type: 'f'
, (err, list) ->
  # list may include 'test/temp/file1', 'test/temp/file2', 'test/temp/dir1/file11'

File size

With the minsize and maxsize options it is possible to specify the exact size of the matching files in bytes:

  • use an Integer value as number of bytes
  • use a String like 1M or 100k

Example

CoffeeScript Code
fs = require 'alinex-fs'
fs.find '/tmp/some/directory',
  filter:
    maxsize: 1024 * 1024
, (err, list) ->
  # list contains only files larger than 1MB

Owner and Group

You may also specify files based on the user which owns the files or the group of the files.

Both may be specified as id (uid or gid) or using the alias name.

  • user - Integer|String owner name or id
  • group - Integer|String owner group name or id

Example

CoffeeScript Code
fs = require 'alinex-fs'
fs.find '/tmp/some/directory',
  filter:
    user: process.uid
, (err, list) ->
  # list contains only files belonging to the current user

Time specification

It is also possible to select files based on their creation, last modified or last accessed time.

Specify the Before and After time appended to one of the above as:

  • Unix timestamp
  • ISO-8601 date formats
  • some local formats (based on platform support for Date.parse())
  • time difference from now (human readable)

The following time definitions are an example what you may use:

  • yesterday, 2 days ago, last Monday to specify a day from now
  • yesterday 15:00, yesterday at 15:00 to also specify the time
  • 1 March, 1st March specifies a date in this year
  • 1 March 2014, 1st March 2014, '03/01/13,01.03.2014` all specifiying the 1st of march
  • 9:00, 9:00 GMT+0900 to specify a time today or in combination with a date
  • last night, 00:00

If only a day is given it will use 12:00 as the time.

Example

CoffeeScript Code
fs = require 'alinex-fs'
fs.find '/tmp/some/directory',
  filter:
    modifiedBefore: 'yesterday 12:00'
, (err, list) ->
  # list contains only files older than yesterday 12 o'clock

User defined function

With the test parameter you may add an user defined function which will be called to check each file. It will get the file path and options array so you may also add some configuration therefore in additional option values.

Asynchronous call:

CoffeeScript Code
fs = require 'alinex-fs'
fs.find '.',
  filter:
    test: (file, options, cb) ->
      cb ~file.indexOf 'ab'
, (err, list) ->
  console.log "Found #{list.length} matches."

Or use synchronous calls:

CoffeeScript Code
fs = require 'alinex-fs'
list = fs.findSync 'test/temp',
  filter:
    test: (file, options) ->
      return ~file.indexOf 'ab'
console.log "Found #{list.length} matches."