JSPATH – Документация

JSPATH

JSPATH — это предметно-ориентированный язык (DSL), который позволяет находить и извлекать данные из JSON-документов. С помощью JSPATH вы можете выбирать элементы JSON, чтобы получить содержащиеся в них данные.

Пример данных:

{
  "automobiles": [
    { "maker": "Nissan", "model": "Teana", "year": 2011 },
    { "maker": "Honda", "model": "Jazz", "year": 2010 },
    { "maker": "Honda", "model": "Civic", "year": 2007 },
    { "maker": "Toyota", "model": "Yaris", "year": 2008 },
    { "maker": "Honda", "model": "Accord", "year": 2011 }
  ],
  "motorcycles": [{ "maker": "Honda", "model": "ST1300", "year": 2012 }]
}

Пример пути к данным — .automobiles{.maker === "Honda" && .year > 2009}.model

Результат:

["Jazz", "Accord"]

Предикаты

Предикаты JSPATH позволяют писать очень специфические правила для элементов, которые вы хотите выбрать при построении выражения пути. Предикаты — это фильтры, которые ограничивают элементы, выбранные путем расположения. Существует два возможных типа предикатов: объектные и позиционные предикаты.

Объектные предикаты

Объектные предикаты могут использоваться в выражении пути для фильтрации подмножества элементов в соответствии с булевыми выражениями, работающими со свойствами каждого элемента. Все объектные предикаты заключаются в фигурные скобки ({ и }).

В JSPATH внутри объектного предиката могут использоваться следующие базовые выражения:

числовые литералы (например, 1.23)
строковые литералы (например, "John Gold")
булевы литералы (true и false)
литерал null (null)
вложенные пути (например, .nestedProp.deeplyNestedProp)
вложенные предикаты (например, .prop{.nestedProp{.deeplyNestedProp{.stillMore || .yetAnother} || .otherDeeplyNested}})

Кроме того, внутри объектного предиката допустимы следующие типы операторов:

операторы сравнения
операторы сравнения строк
логические операторы
арифметические операторы

Операторы сравнения

оператор

описание

пример

==

возвращает true, если оба операнда равны

.books{.id == "1"}

===

возвращает true, если оба операнда строго равны без преобразования типов

.books{.id === 1}

!=

возвращает true, если операнды не равны

.books{.id != "1"}

!==

возвращает true, если операнды не равны и/или не одного типа данных

.books{.id !== 1}

>

возвращает true, если левый операнд больше правого

.books{.id > 1}

>=

возвращает true, если левый операнд больше или равен правому

.books{.id >= 1}

<

возвращает true, если левый операнд меньше правого

.books{.id < 1}

<=

возвращает true, если левый операнд меньше или равен правому

.books{.id <= 1}

JSPATH использует следующие правила для сравнения массивов и объектов разных типов:

если оба сравниваемых операнда являются массивами, то сравнение будет истинным, если существует элемент в первом массиве и элемент во втором массиве, такие что результат сравнения этих двух элементов истинен
если один операнд является массивом, а другой нет, то сравнение будет истинным, если существует элемент в массиве, такой что результат сравнения этого элемента и другого операнда истинен
примитивы сравниваются как обычные примитивы javascript

Операторы сравнения строк

Если оба операнда являются строками, доступны дополнительные операторы сравнения:

оператор

описание

пример

==

возвращает true, если обе строки равны

.books{.title == "clean code"}

^==

с учетом регистра; возвращает true, если левый операнд начинается с правого

.books{.title ^== "Javascript"}

^=

без учета регистра; возвращает true, если левый операнд начинается с правого

.books{.title ^= "javascript"}

==^

с учетом регистра; возвращает true, если правый операнд начинается с левого

.books{.title ==^ "Javascript"}

=^

без учета регистра; возвращает true, если правый операнд начинается с левого

.books{.title =^ "javascript"}

$==

с учетом регистра; возвращает true, если левый операнд заканчивается правым

.books{.title $== "Javascript"}

$=

без учета регистра; возвращает true, если левый операнд заканчивается правым

.books{.title $= "javascript"}

==$

с учетом регистра; возвращает true, если правый операнд заканчивается левым

.books{.title ==$ "Javascript"}

=$

без учета регистра; возвращает true, если правый операнд заканчивается левым

.books{.title =$ "javascript"}

*==

с учетом регистра; возвращает true, если левый операнд содержит правый

.books{.title *== "Javascript"}

*=

без учета регистра; возвращает true, если левый операнд содержит правый

.books{.title *= "javascript"}

==*

с учетом регистра; возвращает true, если правый операнд содержит левый

.books{.title ==* "Javascript"}

=*

без учета регистра; возвращает true, если правый операнд содержит левый

.books{.title =* "javascript"}

Логические операторы

оператор

описание

пример

&&

возвращает true, если оба операнда true

.books{.price > 19 && .author.name === "Robert C. Martin"}

||

возвращает true, если один или оба операнда true

.books{.title === "Maintainable JavaScript" || .title === "Clean Code"}

!

возвращает true, если операнд ложный

.books{!.title}

В JSPATH логические операторы преобразуют свои операнды в логические значения, используя следующие правила:

если операнд является массивом с длиной больше 0, результат будет true, иначе false
в любых других случаях используется приведение с помощью двойного отрицания в JavaScript (!!)

Арифметические операторы

оператор

описание

+

сложение

-

вычитание

*

умножение

/

деление

%

остаток от деления

Приоритет операторов

приоритет

оператор

1 (наивысший)

!, унарный -

*, /, %

+, бинарный -

<, <=, >, >=

==, ===, !=, !==, ^=, ^==, $==, $=, *=, *==, =^, ==^, =$, ==$, =*, ==*

&&

7 (низший)

||

Скобки (( и )) используются для явного обозначения приоритета путем группировки частей выражения, которые должны быть вычислены первыми.

Примеры

// найти все названия книг, автором которых является Robert C. Martin
'.books{.author.name === "Robert C. Martin"}.title';
/* ['Clean Code', 'Agile Software Development'] */

// найти все названия книг с ценой меньше 17
".books{.price < 17}.title";
/* ['Maintainable JavaScript', 'JavaScript: The Good Parts'] */

Позиционные предикаты

Позиционные предикаты позволяют фильтровать элементы по их позиции в контексте. Все позиционные предикаты заключаются в квадратные скобки ([ и ]).

JSPATH поддерживает четыре типа позиционных предикатов – также известных как методы среза:

оператор

описание

пример

[index]

возвращает элемент в контексте с индексом index – первый элемент имеет индекс 0, позиционные предикаты начинаются с нуля

[3] возвращает четвертый элемент в контексте

[start:]

возвращает диапазон элементов, индекс которых в контексте больше или равен start

[2:] возвращает элементы, индекс которых больше или равен 2

[:end]

возвращает диапазон элементов, индекс которых в контексте меньше end

[:5] возвращает элементы с индексами от 0 до 4

[start:end]

возвращает диапазон элементов, индекс которых в контексте больше или равен start и меньше end

[2:5] возвращает элементы с индексами 2, 3 и 4

index, start или end могут быть отрицательными числами, что означает, что JSPATH считает с конца, а не с начала:

пример

описание

[-1]

возвращает последний элемент в контексте

[-3:]

возвращает последние три элемента в контексте

Примеры

Найти название первой книги

.books[0].title

Найти первое название из книг

.books.title[0]

Найти название последней книги

.books[-1].title

Найти названия двух первых книг

.books[:2].title

Найти названия двух последних книг

.books[-2:].title

Найти названия двух книг, начиная со второй позиции

.books[1:3].title

Множественные предикаты

Вы можете использовать более одного предиката – любую комбинацию объектных и позиционных предикатов. Результат будет содержать только элементы, соответствующие всем предикатам.

Примеры

Найти название первой книги, цена которой меньше 15 и больше 5

.books{.price < 15}{.price > 5}[0].title

Вложенные предикаты

Вы можете вкладывать предикаты настолько глубоко, насколько хотите — это избавляет от необходимости повторять глубокие вложенные пути каждый раз, сокращая длину запроса. Подобно оператору "with" в JavaScript, все свойства объекта становятся свойствами первого уровня внутри вложенного предиката.

Примеры

Длинные вложенные пути: найти книги различных авторов стоимостью менее $20

.books{.price < 20 && (.author.name *== "Zakas" || .author.name *== "Martin")}.title

Вложенные предикаты: тот же запрос, однако ".author.name" не повторяется. Для JSON с множеством уровней это позволяет создавать гораздо более компактные запросы.

.books{.price < 20 && .author{.name *== "Zakas" || .name *== "Martin"}}.title

📌 Следующий шаг: Команды →

📌 Также может быть полезно: HTTP запросы | Сценарии