<commit_before># Pathogen

*General-purpose path library for PHP.*

[![Build Status]](http://travis-ci.org/eloquent/pathogen)
[![Test Coverage]](http://lqnt.co/pathogen/artifacts/tests/coverage/)

## Installation

Available as [Composer](http://getcomposer.org/) package
[eloquent/pathogen](https://packagist.org/packages/eloquent/pathogen).

## What is Pathogen?

Pathogen is a library for path manipulation. Pathogen supports file system paths
including Unix and Windows style paths, but is truly a general-purpose path
implementation, capable of representing URI paths and other path-like structures
while providing a comprehensive API.

## Basic concepts

### Path atoms

In Pathogen, a path consists of a sequence of "atoms". Atoms are the individual
sections of the path hierarchy. Given the path `/path/to/foo`, the sequence of
atoms would be `path`, `to`, `foo`. The slash character is referred to as the
"separator".

The atoms `.` and `..` have special meaning in Pathogen. The single dot (`.`) is
referred to as the "self atom" and is typically used to reference the current
path. The double dot (`..`) is referred to as the "parent atom" and is used to
reference the path above the current one. Anyone familiar with typical file
system paths should be familiar with their behaviour already.

### Absolute vs. relative paths

In Pathogen, absolute and relative paths are represented by two different
classes. While both classes implement a common `PathInterface`, other methods
are provided by the `AbsolutePathInterface` or the `RelativePathInterface`
respectively.

This distinction provides, amongst other benefits, the ability to harness PHP's
type hinting to restrict the type of path required:

```php
use Eloquent\Pathogen\AbsolutePathInterface;
use Eloquent\Pathogen\PathInterface;
use Eloquent\Pathogen\RelativePathInterface;

function anyPath(PathInterface $path)
{
    // accepts any path
}

function absoluteOnly(AbsolutePathInterface $path)
{
    // accepts only absolute paths
}

function relativeOnly(AbsolutePathInterface $path)
{
    // accepts only relative paths
}
```

### The "root" path

The "root" path is considered the top-most absolute path, and is represented as
a single separator with no atoms (`/`).

### The "self" path

The "self" path is considered to point to the "current" path, and is represented
as a single "self" atom (`.`).

### Path normalization

Normalization of a path is the process of converting a path to its simplest or
"canonical" form. This means resolving as many of the "self" and "parent" atoms
as possible. For example, the path `/path/to/foo/../bar` normalizes to
`/path/to/bar`.

Normalization works differently for absolute and relative paths. Absolute paths
can always be resolved to a definite form with no "self" or "parent" atoms.
Relative paths can often be simplified, but may still contain these special
atoms. For example, the path `../foo/../..` will actually normalize to `../..`.

Note that for absolute paths, the "root" path (`/`) is the top-most path to
which "parent" atoms will normalize. That is, paths with more parent atoms than
regular atoms, like `/..`, `/../..`, or `/foo/../..` will all normalize to be
the root path (`/`).

<!-- references -->
[Build Status]: https://raw.github.com/eloquent/pathogen/gh-pages/artifacts/images/icecave/regular/build-status.png
[Test Coverage]: https://raw.github.com/eloquent/pathogen/gh-pages/artifacts/images/icecave/regular/coverage.png<commit_msg>Updated documentation.<commit_after># Pathogen

*General-purpose path library for PHP.*

[![Build Status]](http://travis-ci.org/eloquent/pathogen)
[![Test Coverage]](http://lqnt.co/pathogen/artifacts/tests/coverage/)

## Installation

Available as [Composer][] package [eloquent/pathogen][].

## What is Pathogen?

Pathogen is a library for path manipulation. Pathogen supports file system paths
including Unix and Windows style paths, but is truly a general-purpose path
implementation, capable of representing URI paths and other path-like structures
while providing a comprehensive API.

## Pathogen concepts

### Path atoms

In Pathogen, a path consists of a sequence of 'atoms'. Atoms are the individual
sections of the path hierarchy. Given the path `/path/to/foo`, the sequence of
atoms would be `path`, `to`, `foo`. The slash character is referred to as the
'separator'.

The atoms `.` and `..` have special meaning in Pathogen. The single dot (`.`) is
referred to as the 'self atom' and is typically used to reference the current
path. The double dot (`..`) is referred to as the 'parent atom' and is used to
reference the path above the current one. Anyone familiar with typical file
system paths should be familiar with their behaviour already.

### Absolute vs. relative paths

In Pathogen, absolute and relative paths are represented by two different
classes. While both classes implement a common [PathInterface][], other methods
are provided by the [AbsolutePathInterface][] or the [RelativePathInterface][]
respectively.

This distinction provides, amongst other benefits, the ability to harness PHP's
type hinting to restrict the type of path required:

```php
use Eloquent\Pathogen\AbsolutePathInterface;
use Eloquent\Pathogen\PathInterface;
use Eloquent\Pathogen\RelativePathInterface;

function anyPath(PathInterface $path)
{
    // accepts any path
}

function absoluteOnly(AbsolutePathInterface $path)
{
    // accepts only absolute paths
}

function relativeOnly(RelativePathInterface $path)
{
    // accepts only relative paths
}
```

### Special paths

The 'root' path is considered the top-most absolute path, and is represented as
a single separator with no atoms (`/`).

The 'self' path is considered to point to the 'current' path, and is represented
as a single self atom (`.`).

### Path factories

Pathogen provides factory classes for creating paths. All path factories
implement [PathFactoryInterface][] which allows a path to be created from
various kinds of input. This is the typical way in which path instances are
created, although the path classes *can* be constructed directly if desired.

A simple example of path factory usage is as follows:

```php
use Eloquent\Pathogen\FileSystem\FileSystemPathFactory;

$factory = new FileSystemPathFactory;

$pathFoo = $factory->create('/path/to/foo');
$pathBar = $factory->create('C:/path/to/bar');
```

### Path resolution

Resolution of a path involves taking a path which may be relative or absolute,
and figuring out where that path points to, given a known 'base' path. The
result of path resolution will always be an absolute path.

For example, consider a current path of `/path/to/foo`. If you have a relative
path of `bar/baz`, this will resolve to `/path/to/foo/bar/baz`. If you have an
absolute path of `/path/to/qux`, this will not change after resolution, as it is
already an absolute path.

Path resolution is achieved by passing a path through a path resolver, like so:

```php
use Eloquent\Pathogen\FileSystem\FileSystemPathFactory;
use Eloquent\Pathogen\Resolver\PathResolver;

$factory = new FileSystemPathFactory;
$resolver = new PathResolver;

$basePath = $factory->create('/path/to/foo');
$path = $factory->create('bar/baz');

$finalPath = $resolver->resolve($basePath, $path);
echo $finalPath->string(); // outputs '/path/to/foo/bar/baz'
```

### Path normalization

Normalization of a path is the process of converting a path to its simplest or
*canonical* form. This means resolving as many of the self and parent atoms as
possible. For example, the path `/path/to/foo/../bar` normalizes to
`/path/to/bar`.

Normalization works differently for absolute and relative paths. Absolute paths
can always be resolved to a canonical form with no self or parent atoms.
Relative paths can often be simplified, but may still contain these special
atoms. For example, the path `../foo/../..` will actually normalize to `../..`.

Note that for absolute paths, the root path (`/`) is the top-most path to which
parent atoms will normalize. That is, paths with more parent atoms than regular
atoms, like `/..`, `/../..`, or `/foo/../..` will all normalize to be the root
path (`/`).

Normalization typically never takes place in Pathogen unless it is required for
a calculation, or done manually through the API. If a normalized path is
required for some reason, this is left to the developer to handle:

```php
use Eloquent\Pathogen\FileSystem\FileSystemPathFactory;
use Eloquent\Pathogen\Normalizer\PathNormalizer;

$factory = new FileSystemPathFactory;
$normalizer = new PathNormalizer;

$path = $factory->create('/path/./to/foo/../bar');

$normalizedPath = $normalizer->normalize($path);
echo $normalizedPath->string(); // outputs '/path/to/bar'
```

<!-- references -->
[AbsolutePathInterface]: src/Eloquent/Pathogen/AbsolutePathInterface.php
[Build Status]: https://raw.github.com/eloquent/pathogen/gh-pages/artifacts/images/icecave/regular/build-status.png
[Composer]: http://getcomposer.org/
[eloquent/pathogen]: https://packagist.org/packages/eloquent/pathogen
[PathFactoryInterface]: src/Eloquent/Pathogen/Factory/PathFactoryInterface.php
[PathInterface]: src/Eloquent/Pathogen/PathInterface.php
[RelativePathInterface]: src/Eloquent/Pathogen/RelativePathInterface.php
[Test Coverage]: https://raw.github.com/eloquent/pathogen/gh-pages/artifacts/images/icecave/regular/coverage.png
{'fraction_non_alphanumeric': 0.1024682124158564, 'fraction_numerical': 0.0, 'mean_word_length': 4.598086124401914, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 14, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6008894', 'n_tokens_mistral': 2630, 'n_tokens_neox': 2550, 'n_words': 1095}