<commit_before># Path & query principles

* [Path principle](#path-principle)
    * [Path items](#path-items)
    * [Path items syntax](#path-items-syntax)
* [Query, a quick overview](#query-a-quick-overview)
    * [path-arrays](#path-arrays)
* [Path ids](#path-ids)
    * [Usage](#usage)
    * [Explicit or internal id](#explicit-or-internal-id)
    * [Ids and modifiers](#ids-and-modifiers)     
* [Query, let's go further](#query-lets-go-further)
    * [Embedded path-arrays](#embedded-path-arrays)
    * [Result scope](#result-scope)
    * [Single value path-array](#single-value-path-array)
* [Symbols](#symbols)
* [Keywords](#keywords)
* [Modifiers](#modifiers)


## Path principle

Grabbag offer an alternative to PHP chain to get value from PHP elements (objects or arrays).
It principle is to use a path that acts similarly to PHP chain but with some benefits.

for example, a PHP chain such as : 
```php
$element->getThat()->is['a']['path'];
```

```php
$result = Grabbag::grab($element, 'that/is/a/path');
```

Grabbag Path are directly [inspired from Linux path syntax](faq.md#why-choosing-linux-path-like-syntax). That was made on purpose to look familiar for developers and make Grabbag basic usage as easiest as possible.


### Path items

Path items are separated by slashes (so are the directories in linux path) an refer to a PHP element (objet, array, method or variable).

Array keys or object properties can be accessed the same way : 
```
/myObject/myProperty
/myArray/myKey
```
No need to use distinct syntax as in raw PHP :
```php
$myObject->myProperty; // Accessing an object's public property.
$myArray['myKey'];     // Accessing an array keyed item.
```
When path item refers an object getter method, 'get' can be omitted so can be the parenthesis if no parameter is required.

Following paths are equivalent. 

```
/myObject/getSometing()
/myObject/something()
/myObject/something
```
Method items can have one but [only one parameter provided](faq.md#why-only-one-parameter-for-method-path-items) (for now) : Method items aims to access getter method. one parameter is all we need in that case.  

Following paths are equivalent. 
```
/myObject/getSometing("param")
/myObject/something("param")
```
Path item allowing to access directly to a PHP element is called an accessor. There is some other types of path items (keywords and symbols) we'll see later.
## Query, a quick overview

We talked about path till now ? flub! we would have talk about query !

in fact, the second parameter Grabbag::grab method accepts is not a path but a query.
All will be explained as soon as i tell you the simplest form of a query is a path.

So now the question is : what a query could be if it's non (only) a path !

### path-arrays

path-arrays gathers paths in order to produce structured arrays.

**Example :**
```php
$result = Grabbag::grab($subject, [
    "my/first/path",
    "my/second/path"
]);
```
**Example result  :** <commit_msg>Typos in doc<commit_after># Path & query principles

* [Path principle](#path-principle)
    * [Path items](#path-items)
    * [Path items syntax](#path-items-syntax)
* [Query, a quick overview](#query-a-quick-overview)
    * [path-arrays](#path-arrays)
* [Path ids](#path-ids)
    * [Usage](#usage)
    * [Explicit or internal id](#explicit-or-internal-id)
    * [Ids and modifiers](#ids-and-modifiers)     
* [Query, let's go further](#query-lets-go-further)
    * [Embedded path-arrays](#embedded-path-arrays)
    * [Result scope](#result-scope)
    * [Single value path-array](#single-value-path-array)
* [Symbols](#symbols)
* [Keywords](#keywords)
* [Modifiers](#modifiers)


## Path principle

Grabbag offer an alternative to PHP chain to get value from PHP elements (objects or arrays).
It principle is to use a path that acts similarly to PHP chain but with some benefits.

for example, a PHP chain such as : 
```php
$element->getThat()->is['a']['path'];
```

```php
$result = Grabbag::grab($element, 'that/is/a/path');
```

Grabbag Path are directly [inspired from Linux path syntax](faq.md#why-choosing-linux-path-like-syntax). That was made on purpose to look familiar for developers and make Grabbag basic usage as easiest as possible.


### Path items

Path items are separated by slashes (so are the directories in linux path) an refer to a PHP element (objet, array, method or variable).

Array keys or object properties can be accessed the same way : 
```
/myObject/myProperty
/myArray/myKey
```
No need to use distinct syntax as in raw PHP :
```php
$myObject->myProperty; // Accessing an object's public property.
$myArray['myKey'];     // Accessing an array keyed item.
```
When path item refers an object getter method, 'get' can be omitted so can be the parenthesis if no parameter is required.

Following paths are equivalent. 

```
/myObject/getSometing()
/myObject/something()
/myObject/something
```
Method items can have one but [only one parameter provided](faq.md#why-only-one-parameter-for-method-path-items) (for now) : Method items aims to access getter method. one parameter is all we need in that case.  

Following paths are equivalent. 
```
/myObject/getSometing("param")
/myObject/something("param")
```
Path item allowing to access directly to a PHP element is called an accessor. There is some other types of path items (keywords and symbols) we'll see later.
## Query, a quick overview

We talked about path till now ? flub! we would have talk about query !

In fact, the second parameter Grabbag::grab method accepts is not a path but a query.
All will be explained as soon as i tell you the simplest form of a query is a path.

So now the question is : what a query could be if it's non (only) a path !

### path-arrays

path-arrays gather paths in order to produce structured arrays.

**Example :**
```php
$result = Grabbag::grab($subject, [
    "my/first/path",
    "my/second/path"
]);
```
**Example result  :** 
{'fraction_non_alphanumeric': 0.12144790257104195, 'fraction_numerical': 0.0, 'mean_word_length': 4.191395961369622, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 9, 'https://': 0, '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': '5792201', 'n_tokens_mistral': 1850, 'n_tokens_neox': 1727, 'n_words': 710}