Specs
At its core, the output of pls
is a list of nodes. Each node in the list has
a specific color, style and importance, all of which collectively determine how
it is rendered and displayed.
pls
uses specs to match each node to its visual properties, using a powerful
regex matching system, which allows nodes to be matched by their name, extension
or even fragments of both.
Spec
A spec consists of four components, of which only the first is mandatory.
-
pattern:
regex::bytes::Regex
This is a regex pattern that will be compared against the node name. If the node matches this regex, this spec will be associated with the node.
-
icon:
String
This is the name, and not the actual glyph, of the icon to use for nodes matching this spec. When specs cascade, the last defined icon definition is used. If no specs match a node, the default icon for the node type is used.
-
style:
String
This is a markup directive that must be applied to the nodes that match this spec. When specs cascade, their directives are combined with latter rules overriding previous ones if they conflict.
-
importance:
i8
This defines the importance level of the file and overrides the default value (determined by the leading dot).
-
collapse:
Collapse
Collapse
The goal of collapsing is to indicate that a node is a derivative of another adjacent node. Collapsing can be performed in two ways.
-
name
In this case, a node with a specific name is collapsed into another with a specific name. For example,
Cargo.lock
collapses intoCargo.toml
. -
ext
In this case, every node with a specific extension is collapsed into another node with the same stem but different extension. For example,
index.js
andlib.js
collapse intoindex.ts
andlib.ts
respectively.
Configuration
Specs are configured in the .pls.yml
file.
Examples
Consider a typical JavaScript project. When listing it with pls
the output
is very plain. That's because pls
ships with a very lean config out of the
box.
src/ .gitignore justfile package.json pnpm-lock.yaml prettier.config.js .prettierignore README.md tsconfig.json
But we can make some things better here.
- Use better icons for
package.json
andpnpm-lock.yaml
. - Make
pnpm-lock.yaml
collapse intopackage.json
. - Add icons for files related to Prettier.
- Add icons and color for TypeScript and JavaScript files.
- Make JavaScript files collapse into their corresponding TypeScript files.
- Emphasise
README.md
andjustfile
as they are starting files.
Let's add a spec file to it.
src/ .gitignore justfile package.json └─ pnpm-lock.yaml .pls.yml prettier.config.js .prettierignore README.md tsconfig.json
index.ts └─ index.js lib.ts └─ lib.js no_child.ts no_parent.js