Skip to content
pls

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.

  • icons: String[]

    This is a list of names, and not the actual glyphs, 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.

    One spec may define multiple icons. This is useful to specify an SVG icon with a Nerd Font fallback. When a terminal doesn't support SVGs, the SVG icons are skipped over and the Nerd Font fallback is rendered instead.

  • 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$
    icons:
      - typescript
    style: rgb(49,120,198)
  - pattern: \.js$
    icons:
      - javascript
    style: rgb(247,223,30)
    importance: -1
    collapse:
      ext: ts
  - pattern: prettier
    icons:
      - broom
  - pattern: ^package\.json$
    icons:
      - package
  - pattern: ^pnpm-lock\.yaml$
    icons:
      - 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