npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

prprcssr

v2.0.0-rc1

Published

Preprocessor

Downloads

4

Readme

Advanced preprocessing language.

Syntax

Directives

Directives start with @ symbol.

@set

Assigns a value of an expression to a variable.

Variables are defined in a global context.

Example:

Sets SOMEVAR to 1:

@macro

@endmacro can be replaced with @end.

Defines a code region that can take it's own parameters. Macros are declared in a global scope. Macro parameters are only available within the macro scope and override global variables with the same name (but do not affect them).

Macros can be used:

  • via @include directive:

  • inline:

    When macros are used inline:

    • no line control statements are generated for the output inside the macro scope
    • trailing newline is trimmed from macro output

Examples:

Then some_macro can be used as:

which will produce:

Hello, username!
Roses are red,
And violets are of undefined color.

The same macro used inline:

will ouput:

[[[ Hello, username!
Roses are red,
And violets are blue. ]]]

@include

Includes local file, external source or a macro.

Macro

Local Files

Remote Files

From GitHub

Where:

  • user – user/organization name
  • repo – repository name
  • ref – git reference (branch name or tag, defaults to master)

Examples:

  • Head of the default branch

  • Head of the develop branch

  • Tag v2.0.0:

Authentication

When using GitHub includes, authentication is optional, however:

  • with authentication GitHub API provides much higher rate limits
  • to access private repositories authentication is required

Apart from GitHub username you need to provide either a personal access token or password (which is less secure and not recommended). More info on how to provide those parameters is in usage section.

@include once

Acts the same as @include but has no effect if source has already been included. Macros are always included.

@{...} (inline expressions/macros)

Inserts the value of the enclosed expression or executes a macro.

Example:

results in the following output:

Hello, Someone, the result is: 56088.

@while

While-loop. loop variable is available in @while loops.

@endwhile can be replaced with @end.

Example

@repeat

Loop that repeats a certain number of iterations. loop variable is available in @repeat loops.

@endrepeat can be replaced with @end.

Example:

outputs:

  loop.iteration: 1
  loop.iteration: 2
  loop.iteration: 3

@if – @elseif – @else

Conditional directive.

@endif can be replaced with @end.

Example:

@error

Emits an error.

Example:

Filters

"Filter" | operator allows to pass a value through any of supported functions.

which is equivalent to:

Example:

Expressions

Directives that have parameters allow usage of expression syntax.

For example:

  • @include <source:expression>
  • @set <variable:identifier> <value:expression>
  • @if <condition:expression>
  • @elseif <condition:expression>
  • @{<expression>} (inline expressions)

Types

The following types are supported in expressions:

  • numbers (eg: 1,1E6, 1e-6, 1.567)
  • strings (eg: "abc", 'abc')
  • null
  • true
  • false

Operators

Binary

|| && == != < > <= >= + - * / %

Unary

+ - !

Member Expressions

  • somevar.member
  • somevar["member"]
  • ([1, 2, 3])[1]

Conditional Expressions

test ? consequent : alternate

Variables

  • Variables defined by @set statements are available in expressions.
  • Undefined variables are evaluated as null.
  • Variable names can contain $, _, latin letters and digits and can start only with a non-digit.

__LINE__

Line number (relative to the file in which this variable appears).

Example:

__FILE__

Name of the file in which this variable appears.

Example:

__PATH__

Absolute path (not including file name) to the file where this variable appears. Contains url for remote includes.

Example:

loop

Defined inside @while and @repeat loops.

Contains information about the current loop:

  • loop.index – 0-indexed iteration counter
  • loop.iteration – 1-indexed iteration counter

Example:

outputs:

myvar: 11
loop.index: 0
myvar: 10
loop.index: 1
myvar: 9
loop.index: 2

Functions

  • defined(<variable_name>) – returns true if a variable is defined, false otherwise.
  • include(<source>) – includes external source
  • escape(<value>) – escapes special characters in string (\b, \f, \n, \r, \t, \, ', ")
  • base64(<value>) – encodes value as base64
  • min(<numbers>)
  • max(<numbers>)
  • abs(<number>)

Comments

Lines starting with @ followed by space or a line break are treated as comments and not added to the output.

Example:

Usage

Please note that Prprcssr requires Node.js 4.0 and above.

  • As npm library:

    npm i --save Prprcssr

    then

    const Prprcssr = require('prprcssr');
      
    const pp = new Prprcssr();
      
    // (optional) provide GitHub credentials
    pp.machine.readers.github.username = "<usename>";
    pp.machine.readers.github.token = "<personal access token>";
      
    const output = pp.machine.execute(`@include "${inputFile}"`);
  • As CLI:

    Prprcssr provides prprcss command when installed globally:

    where:

    • -l – generate line control statements
    • -D<variable> <value> – define a variable
    • --github-user – GitHub username
    • --github-token – GitHub personal access token or password (not recommended)

Testing

SPEC_LOGLEVEL=<debug|info|warning|error> \
SPEC_GITHUB_USERNAME=<GitHub username> \
SPEC_GITHUB_TOKEN=<GitHub password/access token> \
npm test

License

MIT

Author

Mikhail Yurasov [email protected]