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 into Cargo.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 and lib.js collapse into index.ts and lib.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.

pls

 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 and pnpm-lock.yaml.
Make pnpm-lock.yaml collapse into package.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 and justfile as they are starting files.

Let's add a spec file to it.

icons:
  javascript: "󰌞" # nf-md-language_javascript
  typescript: "󰛦" # nf-md-language_typescript
specs:
  - pattern: \.ts$
    icon: typescript
    style: rgb(49,120,198)
  - pattern: \.js$
    icon: javascript
    style: rgb(247,223,30)
    importance: -1
    collapse:
      ext: ts
  - pattern: prettier
    icon: broom
  - pattern: ^package\.json$
    icon: package
  - pattern: ^pnpm-lock\.yaml$
    icon: lock
    importance: -1
    collapse:
      name: package.json
  - pattern: ^(justfile|README.md)$
    style: green bold
    importance: 2

 src/ 󰊢 .gitignore 󰜎 justfile  package.json └─  pnpm-lock.yaml  .pls.yml 󰃢 prettier.config.js 󰃢 .prettierignore  README.md  tsconfig.json

pls src/

󰛦 index.ts └─ 󰌞 index.js 󰛦 lib.ts └─ 󰌞 lib.js 󰛦 no_child.ts 󰌞 no_parent.js