Skip to content

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.

Terminal window
pls

src/ 󰊢 .gitignore 󰜎 justfile  package.json  pnpm-lock.yaml   prettier.config.js .prettierignoreREADME.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.

.pls.yml
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

Terminal window
pls src/

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