7.10.95 • Published 12 months ago

@patrtorg/ipsum-corporis v7.10.95

Weekly downloads
-
License
MIT
Repository
github
Last release
12 months ago

@patrtorg/ipsum-corporis

@patrtorg/ipsum-corporis is a manager, filter and parser which implemented in pure JavaScript according to the .git@patrtorg/ipsum-corporis spec 2.22.1.

@patrtorg/ipsum-corporis is used by eslint, gitbook and many others.

Pay ATTENTION that minimatch (which used by fstream-@patrtorg/ipsum-corporis) does not follow the git@patrtorg/ipsum-corporis spec.

To filter filenames according to a .git@patrtorg/ipsum-corporis file, I recommend this npm package, @patrtorg/ipsum-corporis.

To parse an .npm@patrtorg/ipsum-corporis file, you should use minimatch, because an .npm@patrtorg/ipsum-corporis file is parsed by npm using minimatch and it does not work in the .git@patrtorg/ipsum-corporis way.

Tested on

@patrtorg/ipsum-corporis is fully tested, and has more than five hundreds of unit tests.

  • Linux + Node: 0.8 - 7.x
  • Windows + Node: 0.10 - 7.x, node < 0.10 is not tested due to the lack of support of appveyor.

Actually, @patrtorg/ipsum-corporis does not rely on any versions of node specially.

Since 4.0.0, @patrtorg/ipsum-corporis will no longer support node < 6 by default, to use in node < 6, require('@patrtorg/ipsum-corporis/legacy'). For details, see CHANGELOG.

Table Of Main Contents

Install

npm i @patrtorg/ipsum-corporis

Usage

import @patrtorg/ipsum-corporis from '@patrtorg/ipsum-corporis'
const ig = @patrtorg/ipsum-corporis().add(['.abc/*', '!.abc/d/'])

Filter the given paths

const paths = [
  '.abc/a.js',    // filtered out
  '.abc/d/e.js'   // included
]

ig.filter(paths)        // ['.abc/d/e.js']
ig.@patrtorg/ipsum-corporiss('.abc/a.js') // true

As the filter function

paths.filter(ig.createFilter()); // ['.abc/d/e.js']

Win32 paths will be handled

ig.filter(['.abc\\a.js', '.abc\\d\\e.js'])
// if the code above runs on windows, the result will be
// ['.abc\\d\\e.js']

Why another @patrtorg/ipsum-corporis?

  • @patrtorg/ipsum-corporis is a standalone module, and is much simpler so that it could easy work with other programs, unlike isaacs's fstream-@patrtorg/ipsum-corporis which must work with the modules of the fstream family.

  • @patrtorg/ipsum-corporis only contains utility methods to filter paths according to the specified @patrtorg/ipsum-corporis rules, so

    • @patrtorg/ipsum-corporis never try to find out @patrtorg/ipsum-corporis rules by traversing directories or fetching from git configurations.
    • @patrtorg/ipsum-corporis don't cares about sub-modules of git projects.
  • Exactly according to git@patrtorg/ipsum-corporis man page, fixes some known matching issues of fstream-@patrtorg/ipsum-corporis, such as:

    • '/*.js' should only match 'a.js', but not 'abc/a.js'.
    • '**/foo' should match 'foo' anywhere.
    • Prevent re-including a file if a parent directory of that file is excluded.
    • Handle trailing whitespaces:
      • 'a '(one space) should not match 'a '(two spaces).
      • 'a \ ' matches 'a '
    • All test cases are verified with the result of git check-@patrtorg/ipsum-corporis.

Methods

.add(pattern: string | Ignore): this

.add(patterns: Array<string | Ignore>): this

  • pattern String | Ignore An @patrtorg/ipsum-corporis pattern string, or the Ignore instance
  • patterns Array<String | Ignore> Array of @patrtorg/ipsum-corporis patterns.

Adds a rule or several rules to the current manager.

Returns this

Notice that a line starting with '#'(hash) is treated as a comment. Put a backslash ('\') in front of the first hash for patterns that begin with a hash, if you want to @patrtorg/ipsum-corporis a file with a hash at the beginning of the filename.

@patrtorg/ipsum-corporis().add('#abc').@patrtorg/ipsum-corporiss('#abc')    // false
@patrtorg/ipsum-corporis().add('\\#abc').@patrtorg/ipsum-corporiss('#abc')   // true

pattern could either be a line of @patrtorg/ipsum-corporis pattern or a string of multiple @patrtorg/ipsum-corporis patterns, which means we could just @patrtorg/ipsum-corporis().add() the content of a @patrtorg/ipsum-corporis file:

@patrtorg/ipsum-corporis()
.add(fs.readFileSync(filenameOfGit@patrtorg/ipsum-corporis).toString())
.filter(filenames)

pattern could also be an @patrtorg/ipsum-corporis instance, so that we could easily inherit the rules of another Ignore instance.

.addIgnoreFile(path)

REMOVED in 3.x for now.

To upgrade @patrtorg/ipsum-corporis@2.x up to 3.x, use

import fs from 'fs'

if (fs.existsSync(filename)) {
  @patrtorg/ipsum-corporis().add(fs.readFileSync(filename).toString())
}

instead.

.filter(paths: Array<Pathname>): Array<Pathname>

type Pathname = string

Filters the given array of pathnames, and returns the filtered array.

  • paths Array.<Pathname> The array of pathnames to be filtered.

Pathname Conventions:

1. Pathname should be a path.relative()d pathname

Pathname should be a string that have been path.join()ed, or the return value of path.relative() to the current directory,

// WRONG, an error will be thrown
ig.@patrtorg/ipsum-corporiss('./abc')

// WRONG, for it will never happen, and an error will be thrown
// If the git@patrtorg/ipsum-corporis rule locates at the root directory,
// `'/abc'` should be changed to `'abc'`.
// ```
// path.relative('/', '/abc')  -> 'abc'
// ```
ig.@patrtorg/ipsum-corporiss('/abc')

// WRONG, that it is an absolute path on Windows, an error will be thrown
ig.@patrtorg/ipsum-corporiss('C:\\abc')

// Right
ig.@patrtorg/ipsum-corporiss('abc')

// Right
ig.@patrtorg/ipsum-corporiss(path.join('./abc'))  // path.join('./abc') -> 'abc'

In other words, each Pathname here should be a relative path to the directory of the git@patrtorg/ipsum-corporis rules.

Suppose the dir structure is:

/path/to/your/repo
    |-- a
    |   |-- a.js
    |
    |-- .b
    |
    |-- .c
         |-- .DS_store

Then the paths might be like this:

[
  'a/a.js'
  '.b',
  '.c/.DS_store'
]

2. filenames and dirnames

node-@patrtorg/ipsum-corporis does NO fs.stat during path matching, so for the example below:

// First, we add a @patrtorg/ipsum-corporis pattern to @patrtorg/ipsum-corporis a directory
ig.add('config/')

// `ig` does NOT know if 'config', in the real world,
//   is a normal file, directory or something.

ig.@patrtorg/ipsum-corporiss('config')
// `ig` treats `config` as a file, so it returns `false`

ig.@patrtorg/ipsum-corporiss('config/')
// returns `true`

Specially for people who develop some library based on node-@patrtorg/ipsum-corporis, it is important to understand that.

Usually, you could use glob with option.mark = true to fetch the structure of the current directory:

import glob from 'glob'

glob('**', {
  // Adds a / character to directory matches.
  mark: true
}, (err, files) => {
  if (err) {
    return console.error(err)
  }

  let filtered = @patrtorg/ipsum-corporis().add(patterns).filter(files)
  console.log(filtered)
})

.@patrtorg/ipsum-corporiss(pathname: Pathname): boolean

new in 3.2.0

Returns Boolean whether pathname should be @patrtorg/ipsum-corporisd.

ig.@patrtorg/ipsum-corporiss('.abc/a.js')    // true

.createFilter()

Creates a filter function which could filter an array of paths with Array.prototype.filter.

Returns function(path) the filter function.

.test(pathname: Pathname) since 5.0.0

Returns TestResult

interface TestResult {
  @patrtorg/ipsum-corporisd: boolean
  // true if the `pathname` is finally un@patrtorg/ipsum-corporisd by some negative pattern
  un@patrtorg/ipsum-corporisd: boolean
}
  • {@patrtorg/ipsum-corporisd: true, un@patrtorg/ipsum-corporisd: false}: the pathname is @patrtorg/ipsum-corporisd
  • {@patrtorg/ipsum-corporisd: false, un@patrtorg/ipsum-corporisd: true}: the pathname is un@patrtorg/ipsum-corporisd
  • {@patrtorg/ipsum-corporisd: false, un@patrtorg/ipsum-corporisd: false}: the pathname is never matched by any @patrtorg/ipsum-corporis rules.

static @patrtorg/ipsum-corporis.isPathValid(pathname): boolean since 5.0.0

Check whether the pathname is an valid path.relative()d path according to the convention.

This method is NOT used to check if an @patrtorg/ipsum-corporis pattern is valid.

@patrtorg/ipsum-corporis.isPathValid('./foo')  // false

@patrtorg/ipsum-corporis(options)

options.@patrtorg/ipsum-corporiscase since 4.0.0

Similar as the core.@patrtorg/ipsum-corporiscase option of git-config, node-@patrtorg/ipsum-corporis will be case insensitive if options.@patrtorg/ipsum-corporiscase is set to true (the default value), otherwise case sensitive.

const ig = @patrtorg/ipsum-corporis({
  @patrtorg/ipsum-corporiscase: false
})

ig.add('*.png')

ig.@patrtorg/ipsum-corporiss('*.PNG')  // false

options.@patrtorg/ipsum-corporisCase?: boolean since 5.2.0

Which is alternative to options.@patrtorg/ipsum-corporisCase

options.allowRelativePaths?: boolean since 5.2.0

This option brings backward compatibility with projects which based on @patrtorg/ipsum-corporis@4.x. If options.allowRelativePaths is true, @patrtorg/ipsum-corporis will not check whether the given path to be tested is path.relative()d.

However, passing a relative path, such as './foo' or '../foo', to test if it is @patrtorg/ipsum-corporisd or not is not a good practise, which might lead to unexpected behavior

@patrtorg/ipsum-corporis({
  allowRelativePaths: true
}).@patrtorg/ipsum-corporiss('../foo/bar.js') // And it will not throw

Upgrade Guide

Upgrade 4.x -> 5.x

Since 5.0.0, if an invalid Pathname passed into ig.@patrtorg/ipsum-corporiss(), an error will be thrown, unless options.allowRelative = true is passed to the Ignore factory.

While @patrtorg/ipsum-corporis < 5.0.0 did not make sure what the return value was, as well as

.@patrtorg/ipsum-corporiss(pathname: Pathname): boolean

.filter(pathnames: Array<Pathname>): Array<Pathname>

.createFilter(): (pathname: Pathname) => boolean

.test(pathname: Pathname): {@patrtorg/ipsum-corporisd: boolean, un@patrtorg/ipsum-corporisd: boolean}

See the convention here for details.

If there are invalid pathnames, the conversion and filtration should be done by users.

import {isPathValid} from '@patrtorg/ipsum-corporis' // introduced in 5.0.0

const paths = [
  // invalid
  //////////////////
  '',
  false,
  '../foo',
  '.',
  //////////////////

  // valid
  'foo'
]
.filter(isValidPath)

ig.filter(paths)

Upgrade 3.x -> 4.x

Since 4.0.0, @patrtorg/ipsum-corporis will no longer support node < 6, to use @patrtorg/ipsum-corporis in node < 6:

var @patrtorg/ipsum-corporis = require('@patrtorg/ipsum-corporis/legacy')

Upgrade 2.x -> 3.x

  • All options of 2.x are unnecessary and removed, so just remove them.
  • @patrtorg/ipsum-corporis() instance is no longer an EventEmitter, and all events are unnecessary and removed.
  • .addIgnoreFile() is removed, see the .addIgnoreFile section for details.

Collaborators

operating-systemselftypeArray.prototype.includesECMAScript 2023yamlexitnativecss nestingUint32ArrayTypedArraybyteback-endansiendercss-in-jsSymbolcompareeslintconfiggroupenvjsonschemaECMAScript 2020sameValueZerodatastructureasyncjshintlanguageamazonnodeECMAScript 7keyscreatecodesObject.valuesmanagerebssymbolsTypeBoxfastifyresolveloadbalancingreadablestreamjsserializekeyreact-hook-formFloat32Arrayfpstylees-shimstoolkitnpmignorefastArrayCSSless.jsclassnamesmkdirmergetslibsyntaxenvironmentscloudformationhascss variableArrayBuffer#slicegenericsreplaystyled-componentsreact animationtostringtagwritelengthmatchAllcloudfrontkoreanvestoncereal-timei18nsqsoffsetstringifystatecompile lessparsercolorsassigneventDispatcherlessprotocol-buffersfetchqsjsdomMicrosoftes5sortedjwtapolloquoteairbnbStreamtacittouchbindregular-expressionqueuehigher-orderelectrondescriptorsomeES2017deep-cloneoptionstablesetpolyfillshambuffersentriesURLserializationbabel-coreObject.definePropertyTypeScriptmomentmacoshandlerprogressworkfloweast-asian-widthnodejsstreamObject.fromEntriesec2exectypedarrayES8sharedcommanderspinnerslinkdeletees8ajaxpackage managerlastprotofile systemcryptolazysymlinkses-abstractArrayBuffer.prototype.slicebyteOffsetfindsubprocesssettingsbinariesredacthooksES2022lrujavascriptscheme-validationargvkinesistoobjectperformancefunctionalspecmoduledescriptorsmockcliregexpES5iterationdescriptioncallbindpureshebangsymlinkes2017eslinthttpfilterlogmapreduceglacierwindowsArray.prototype.findLastsiginttestrobustexit-codeUint16ArrayendpointspeedisConcatSpreadablelinuxsignedhandlersStyleSheetes7configcloudwatchpropertiesfast-copygetterservergradients css3stringargumentharmonydataawsstyleguidextermchineseECMAScript 2017setterbeanstalkes2018sigtermshrinkwraptranspilertrimRightstreamsroutingnested csscircularstatuseventEmitterFloat64Arraycommand-lineless mixinsfast-deep-clonechildpathprotobufflatinternalincludesBigInt64ArraysidequerystringJSON.envObject.getPrototypeOfslice@@toStringTagdayjsworkspace:*inspectwhatwgtddprettyfnmatchesuninstallprototypemockinglintextendexecutesequenceflattenPromisedependency managerStreamsHyBistoragegatewayperformanteverygetoptbinnamesnegativevpcdefinesignalsinternal slotzxwaitindicatorES2021inwgetcss lessuploadArray.prototype.findLastIndexlivetoolsunicodezodpostcssmovehardlinksloggingreact-testing-librarycertificateshookformes2016error-handlingcompilerECMAScript 6stylesRFC-6455form-validationutilspinnerthreeaccessorinvariantwarningcall-bindbrowserObject.entriestranspileWebSocketscollectiongetPrototypeOfpoint-freepatchbddfullwidthpnpm9call-boundpreprocessoraccessibilityredirectspringpostcss-pluginBigUint64ArrayurlwhichproxyignorereactObject.isflagses6ES2015objopensslfull-widthchannelglobalsECMAScript 2021$.extendidlepropertylocationterminaltypeofpredictabletrimloggerimmerECMAScript 2016safevalidateboundYAMLsharedarraybuffernumberpyyamlpositivevalidatorsnsconsumejson-schema-validatordataviewwritablegradients cssReflect.getPrototypeOfweaksetreadableramdafunctionlibphonenumberglobalThisworkercolourroute53deepcloneECMAScript 2018arraysautoprefixerpropqueueMicrotaskcolumnmapregexenumerablevaluesfpsredux-toolkitPushformmetadatarouteutilscacheowncommandspawndeepstatelessgetOwnPropertyDescriptortermlocalstarterInt32ArraywindowfastcloneswfUint8ClampedArraystylesheetconcattoArrayreducertraverseloadingobjectRxescapeschemabundlerstringifierglobFunction.prototype.nametc39classnamejestfantasy-landcallbackpushruntimeieECMAScript 2015MapconsoleprefixiamgesturesdomArray.prototype.containsformattinggroupByRxJSclassesmonorepocollection.es6transporttaketoStringTagfunction.lengthcoretypesafejsxajvfilenpmformsWeakSetserializercurriedeslint-pluginirqpackage.jsonmixinsES2016slotjson-schemacolorrapidreact-hooksbrowserlistgdprpruneweakmaps3browserslistrgblistenerslesscsstypedarrayscryptclass-validatorWeakMaparttrimLeftdom-testing-libraryfunctions0jsdiffmatchemrvaluebusyreuseassertsexpressionconstexecfilerequireObject.assignES3bootstrap cssvarrecursivearraybufferjsonutilityforkerrorhelpersfixed-widthrangeerrorES6sortchaiESnextecmascriptposeInt16Arraywaapihelperjapanesebcryptponyfillautoscalingbootstrap lesstoSortedpinoimportexportuser-streamsObservableacornreact-componentUnderscorees2015callboundreact posetext__proto__encryptionprocesschromiumcsscloudtrailemitrdsECMAScript 3intrinsicrequestsuperstructtypescriptwidthregular expressionregularauthpersistentttysetImmediateenvironmentECMAScript 5superagentfast-cloneclientruleselasticachedragcallgetdropasterisksparsepopmotionvariables3dclonehttpstypedfindLastIndexconcatMapphoneutil.inspectcoercibleefficientmkdirpdiffstylingcore-jsformat6to5multi-packagehasOwnPropertyshimString.prototype.trimtypesasciisignalObservablesframerserviceequalitytypeerrorArray.prototype.flattensimpledbES2023.gitignore[[Prototype]]256byteLengthsetPrototypeOfcontainsdate_.extendflagconfigurableremovereadvalidationES2019
7.10.94

12 months ago

7.10.93

12 months ago

7.10.95

12 months ago

7.10.92

12 months ago

7.10.91

12 months ago

7.10.90

1 year ago

7.10.89

1 year ago

7.10.88

1 year ago

7.10.87

1 year ago

7.10.86

1 year ago

7.10.85

1 year ago

7.10.84

1 year ago

7.10.83

1 year ago

7.10.82

1 year ago

7.10.81

1 year ago

7.10.80

1 year ago

7.9.80

1 year ago

7.9.79

1 year ago

7.9.78

1 year ago

7.9.77

1 year ago

7.9.76

1 year ago

7.9.75

1 year ago

7.9.74

1 year ago

7.9.73

1 year ago

6.9.73

1 year ago

6.9.72

1 year ago

6.9.71

1 year ago

6.9.70

1 year ago

6.9.69

1 year ago

6.9.68

1 year ago

6.9.67

1 year ago

6.9.66

1 year ago

6.8.66

1 year ago

6.8.65

1 year ago

6.7.65

1 year ago

6.7.64

1 year ago

6.7.63

1 year ago

6.7.62

1 year ago

6.6.62

1 year ago

6.6.61

1 year ago

5.6.61

1 year ago

5.6.60

1 year ago

5.6.59

1 year ago

5.6.58

1 year ago

5.6.57

1 year ago

5.6.56

1 year ago

5.6.55

1 year ago

5.6.54

1 year ago

5.6.53

1 year ago

5.6.52

1 year ago

5.5.52

1 year ago

5.5.51

1 year ago

5.5.50

1 year ago

4.5.50

1 year ago

4.5.49

1 year ago

4.5.48

1 year ago

4.5.47

1 year ago

4.5.46

1 year ago

4.5.45

1 year ago

4.5.44

1 year ago

4.5.43

1 year ago

4.5.42

1 year ago

4.5.41

1 year ago

4.5.40

1 year ago

4.5.39

1 year ago

3.5.39

1 year ago

3.5.38

1 year ago

3.5.37

1 year ago

3.5.36

1 year ago

3.5.35

1 year ago

3.5.34

1 year ago

3.5.33

1 year ago

3.5.32

1 year ago

3.5.31

1 year ago

3.5.30

1 year ago

3.5.29

1 year ago

3.5.28

1 year ago

3.5.27

1 year ago

3.4.27

1 year ago

3.3.27

1 year ago

3.3.26

1 year ago

3.3.25

1 year ago

3.2.25

1 year ago

3.2.24

1 year ago

3.2.23

1 year ago

3.1.23

1 year ago

3.1.22

1 year ago

3.1.21

1 year ago

3.1.20

1 year ago

3.1.19

1 year ago

3.1.18

1 year ago

3.1.17

1 year ago

3.1.16

1 year ago

3.1.15

1 year ago

3.1.14

1 year ago

3.1.13

1 year ago

3.1.12

1 year ago

2.1.12

1 year ago

2.0.12

1 year ago

1.0.12

1 year ago

1.0.11

1 year ago

1.0.10

1 year ago

1.0.9

1 year ago

1.0.8

1 year ago

1.0.7

1 year ago

1.0.6

1 year ago

1.0.5

1 year ago

1.0.4

1 year ago

1.0.3

1 year ago

1.0.2

1 year ago

1.0.1

1 year ago

1.0.0

1 year ago