or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-shebang-regex

Regular expression for matching Unix shebang lines at the beginning of files

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/shebang-regex@4.0.x

To install, run

npx @tessl/cli install tessl/npm-shebang-regex@4.0.0

index.mddocs/

Shebang Regex

Shebang Regex provides a simple regular expression for matching Unix shebang lines at the beginning of files. It exports a single RegExp object that can be used to test for the presence of shebang lines and extract both the complete shebang line and the command portion.

Package Information

  • Package Name: shebang-regex
  • Package Type: npm
  • Language: JavaScript (ES module)
  • Installation: npm install shebang-regex

Core Imports

import shebangRegex from 'shebang-regex';

For CommonJS (not officially supported, package is ES module only):

// Use dynamic import for CommonJS environments
const { default: shebangRegex } = await import('shebang-regex');

Basic Usage

import shebangRegex from 'shebang-regex';

const scriptContent = '#!/usr/bin/env node\nconsole.log("Hello world");';

// Test if string starts with a shebang
const hasShebang = shebangRegex.test(scriptContent);
// Result: true

// Extract shebang information
const match = shebangRegex.exec(scriptContent);
// match[0]: '#!/usr/bin/env node' (complete shebang line)
// match[1]: '/usr/bin/env node' (command portion)

console.log('Full shebang:', match[0]);
console.log('Command:', match[1]);

Capabilities

Shebang Detection

Test whether a string begins with a shebang line using the standard RegExp test method.

/**
 * Regular expression for matching Unix shebang lines
 * Pattern: /^#!(.*)/
 * Tests for lines starting with #! and captures the command portion
 * Note: Only matches shebang at the very beginning of the string
 */
declare const shebangRegex: RegExp;

// Standard RegExp.prototype.test method
shebangRegex.test(string: string): boolean;

Usage Example:

import shebangRegex from 'shebang-regex';

// Test various inputs
shebangRegex.test('#!/bin/bash');           // true
shebangRegex.test('#!/usr/bin/env python'); // true  
shebangRegex.test('# This is a comment');   // false
shebangRegex.test('console.log("hello");'); // false

Shebang Extraction

Extract shebang information using the standard RegExp exec method.

/**
 * Execute search for shebang match and extract components
 * @param string - The string to search
 * @returns RegExpExecArray | null - Match array with captured groups or null
 *   - [0]: Complete shebang line (e.g., "#!/usr/bin/env node")
 *   - [1]: Command portion (e.g., "/usr/bin/env node")
 * Note: Returns null if no shebang found at start of string
 */
shebangRegex.exec(string: string): RegExpExecArray | null;

Usage Examples:

import shebangRegex from 'shebang-regex';

// Extract from Node.js script
const nodeScript = '#!/usr/bin/env node\nprocess.exit(0);';
const nodeMatch = shebangRegex.exec(nodeScript);
console.log(nodeMatch[0]); // '#!/usr/bin/env node'
console.log(nodeMatch[1]); // '/usr/bin/env node'

// Extract from Python script  
const pythonScript = '#!/usr/bin/python3\nprint("hello")';
const pythonMatch = shebangRegex.exec(pythonScript);
console.log(pythonMatch[0]); // '#!/usr/bin/python3'
console.log(pythonMatch[1]); // '/usr/bin/python3'

// No match case
const regularCode = 'const x = 42;';
const noMatch = shebangRegex.exec(regularCode);
console.log(noMatch); // null

Standard RegExp Methods

Since shebangRegex is a standard RegExp object, it provides all standard RegExp methods and properties.

/**
 * All standard RegExp methods and properties are available:
 */

// String matching methods
shebangRegex.test(str: string): boolean;
shebangRegex.exec(str: string): RegExpExecArray | null;

// RegExp properties
readonly shebangRegex.source: string;        // '^#!(.*)'
readonly shebangRegex.flags: string;         // ''
readonly shebangRegex.global: boolean;       // false
readonly shebangRegex.ignoreCase: boolean;   // false
readonly shebangRegex.multiline: boolean;    // false
shebangRegex.lastIndex: number;              // 0 (mutable for global regexes)

// Convert to string representation
shebangRegex.toString(): string;             // '/^#!(.*)/'

Types

/**
 * The exported shebangRegex is a standard JavaScript RegExp object
 * with the pattern /^#!(.*)/ for matching Unix shebang lines
 * 
 * Pattern explanation:
 * - ^ : Match start of string
 * - #! : Match literal shebang characters
 * - (.*) : Capture group for the command portion
 */
declare const shebangRegex: RegExp;

export default shebangRegex;

Common Use Cases

CLI Tool File Detection

import shebangRegex from 'shebang-regex';
import { readFileSync } from 'fs';

function isExecutableScript(filePath) {
  const content = readFileSync(filePath, 'utf8');
  return shebangRegex.test(content);
}

function getScriptInterpreter(filePath) {
  const content = readFileSync(filePath, 'utf8');
  const match = shebangRegex.exec(content);
  return match ? match[1] : null;
}

Build Tool Integration

import shebangRegex from 'shebang-regex';

function processScriptFiles(files) {
  return files.map(file => ({
    path: file.path,
    content: file.content,
    isExecutable: shebangRegex.test(file.content),
    interpreter: shebangRegex.exec(file.content)?.[1] || null
  }));
}

Template Processing

import shebangRegex from 'shebang-regex';

function stripShebang(code) {
  return code.replace(shebangRegex, '');
}

function replaceShebang(code, newInterpreter) {
  if (shebangRegex.test(code)) {
    return code.replace(shebangRegex, `#!${newInterpreter}`);
  }
  return `#!${newInterpreter}\n${code}`;
}