README

Extract immutable source-code slices by line, text, or language structure while preserving exact byte ranges and line numbers.

Code Slicer loads a complete source and progressively narrows an immutable CodeSlice. Every slice keeps its language, source name, and original line numbers.

use Alto\Code\Slicer\CodeSource;

$slice = CodeSource::fromFile('src/Command/BuildCommand.php')
    ->slice()
    ->method('execute');

echo $slice->content();
echo $slice->startLine();

Selection stops before presentation. Code Slicer returns source ranges and leaves syntax tokens, annotations, highlighting, and rendering to downstream consumers.

Installation

composer require alto/code-slicer

Code Slicer requires PHP 8.4 or later, the tokenizer extension, and alto/language.

Quick start

Select a PHP method from an in-memory source:

use Alto\Code\Slicer\CodeSource;

$source = CodeSource::fromString(
    <<<'PHP'
final class Checkout
{
    public function complete(): void
    {
        // ...
    }
}
PHP,
    'php',
    'Checkout.php',
);

$slice = $source
    ->slice()
    ->method('complete');

echo $slice->content();

Every selection returns a new CodeSlice; the source and previous slices remain unchanged.

Creating sources

fromFile() reads a local file and resolves its language through alto/language:

$source = CodeSource::fromFile('assets/checkout_controller.js');

$source->language()?->slug; // javascript
$source->name();            // assets/checkout_controller.js
$source->lineCount();

For in-memory code, pass an optional language explicitly. The optional name is metadata and does not imply that a file exists:

use Alto\Code\Slicer\CodeSource;

$source = CodeSource::fromString($code, 'php', 'Example.php');

Unknown and unnamed sources carry null as their language. Text and line selectors still work; structural selectors fail explicitly.

Selecting code

Line numbers are one-based, inclusive, and always refer to the complete source:

$slice = $source->lines(20, 42);
$narrower = $slice->lines(24, 30);

Text selectors are exact, case-sensitive, and limited to the current slice:

$slice = $source->slice()
    ->after('// example:start')
    ->before('// example:end');

Line-boundary selectors include or exclude complete matching lines:

$slice = $source->slice()
    ->afterLine('<!-- example:start -->')
    ->beforeLine('<!-- example:end -->');

Missing boundaries and attempts to expand a slice throw explicit exceptions rather than returning an approximate result.

Structural selectors

The available selectors follow each language's own vocabulary:

Selectors compose to resolve scope and ambiguity:

$slice = $source->slice()
    ->class('CheckoutController')
    ->method('connect');

CSS at-rules can optionally include their prelude:

$slice = $source->slice()->atRule('media', '(width >= 48rem)');

Projection

source() and range() expose the complete source and the selected half-open byte range:

$source = $slice->source();
$range = $slice->range();

$source->content(); // complete source
$range->start;      // inclusive
$range->end;        // exclusive

This lets a downstream adapter parse or highlight the complete source first, then project its text and annotations onto the selected range. content() remains the exact, unmodified source region.

Package boundary

CodeSlice is the raw result of source extraction. Its complete source and byte range let a consumer analyze the full context before projecting the selected region into its own model.

Code Slicer deliberately provides no HTML, SVG, Markdown, syntax tokens, themes, remote loaders, or source rewriting.

Documentation

• Documentation home
• Installation
• Getting started
• Selectors
• Languages

Contributing

Contributions of all kinds are welcome. Visit the project on GitHub to report a bug, suggest a feature, or open a pull request.

Before submitting code, run:

# Runs PHP CS Fixer, PHPStan, and PHPUnit
composer qa

Changes to public behavior should include tests and documentation.

Support

ALTO Code Slicer is open source and independently maintained by Simon André. If it is useful to your work, you can support its continued development through GitHub Sponsors.

Sharing the package or starring it on GitHub also helps.

License

ALTO Code Slicer is released by ALTO PHP under the MIT License.