(انظر أيضًا تراخيص التبعيات التطويرية)

JSONPath Plus

تحليل البيانات وتحويلها واستخراجها بشكل انتقائي من مستندات JSON (وكائنات JavaScript).

تعمل jsonpath-plus على توسيع المواصفات الأصلية لإضافة بعض العوامل الإضافية وتوضح بعض السلوكيات التي لم تحددها المواصفات الأصلية.

جرّب العرض التوضيحي في المتصفح أو Runkit (Node).

يرجى ملاحظة: هذا المشروع لا يحظى حاليًا بصيانة نشطة. قد نقبل طلبات سحب موثقة جيدًا أو بعض التحديثات البسيطة، ولكننا لا ننوي إجراء إصلاحات أو إضافة ميزات جديدة بأنفسنا.

الميزات

• متوافق مع مواصفات jsonpath الأصلية
• إضافات أو توضيحات ملائمة غير موجودة في المواصفات الأصلية:
  • ^ للحصول على العنصر الأب لعنصر مطابق
  • ~ للحصول على أسماء الخصائص للعناصر المطابقة (كمصفوفة)
  • محددات النوع للحصول على:
    • أنواع JSON الأساسية: @null()، @boolean()، @number()، @string()، @array()، @object()
    • @integer()
    • النوع المركب @scalar() (الذي يقبل أيضًا undefined و الأعداد غير المنتهية عند الاستعلام عن كائنات JavaScript بالإضافة إلى جميع الأنواع الأساسية غير الكائنية وغير الدالية)
    • @other() يمكن استخدامه مع معرف من قبل المستخدم

قياس الأداء

تتمتع jsonpath-plus بأداء ثابت مع مجموعات البيانات الكبيرة والصغيرة مقارنة بمكتبات الاستعلام عن JSON الأخرى وفقًا لـ json-querying-performance-testing. يمكنك التحقق من هذه النتائج من خلال تشغيل المشروع بنفسك وإضافة المزيد من حالات الأداء.

التثبيت```shell

npm install jsonpath-plus

## الإعداد

### Node.js```js
const {JSONPath} = require('jsonpath-plus');

const result = JSONPath({path: '...', json});

المتصفح

لاستخدام المتصفح، يمكنك تضمين dist/index-browser-umd.cjs مباشرةً؛ لا حاجة لأي سحر من Browserify:```html

### ESM (المتصفحات الحديثة)

يمكنك أيضًا استخدام ES6 Module imports (للمتصفحات الحديثة):```html
<script type="module">

import {
    JSONPath
} from './node_modules/jsonpath-plus/dist/index-browser-esm.js';

const result = JSONPath({path: '...', json: {}});

</script>

ESM (أدوات التجميع)

أو إذا كنت تقوم بتجميع JavaScript الخاص بك (مثلًا مع Rollup)، فما عليك سوى استخدام، مع ملاحظة أن mainFields يجب أن يتضمن browser لإصدارات المتصفح (بالنسبة لـ Node، الإعداد الافتراضي، الذي يفحص module، يجب أن يكون مناسبًا):```js import {JSONPath} from 'jsonpath-plus';

const result = JSONPath({path: '...', json});

## الاستخدام

التوقيع الكامل المتاح هو:```
const result = JSONPath([options,] path, json, callback, otherTypeCallback);

يمكن التعبير عن الوسائط path وjson وcallback وotherTypeCallback بدلاً من ذلك (إلى جانب أي خصائص أخرى متاحة) في options.

لاحظ أن result سيحتوي على جميع العناصر التي تم العثور عليها (مغلفة اختياريًا في مصفوفة)، بينما يمكن استخدام callback إذا كنت ترغب في تنفيذ عملية معينة عند اكتشاف كل عنصر، حيث يتم تنفيذ دالة الاستدعاء من 0 إلى N مرة اعتمادًا على عدد العناصر المستقلة التي سيتم العثور عليها في النتيجة. راجع الوثائق أدناه لمزيد من المعلومات حول الوسائط المتاحة لـ JSONPath.

انظر أيضًا وثائق API.

الخصائص

الخصائص التي يمكن توفيرها في كائن الخيارات أو في طريقة التقييم (كوسيطة أولى) تشمل:

• path (مطلوب) - تعبير JSONPath كسلسلة نصية (normalized أو unnormalized) أو مصفوفة.
• json (مطلوب) - كائن JSON المراد تقييمه (سواء كان من نوع null أو boolean أو number أو string أو object أو array).
• autostart (الافتراضي: true) - إذا تم توفير هذه القيمة على أنها false، فيمكن للمرء استدعاء طريقة evaluate يدويًا.
• flatten (الافتراضي: false) - ما إذا كانت مصفوفة النتائج المُرجعة ستُسطَّح إلى مصفوفة أحادية البعد.
• resultType (الافتراضي: "value") - يمكن أن يكون بصيغة غير حساسة لحالة الأحرف من "value" أو "path" أو "pointer" أو "parent" أو "parentProperty" لتحديد ما إذا كانت النتائج ستُعاد كقيم العناصر التي تم العثور عليها، أو كمساراتها المطلقة، أو كـ مؤشرات JSON إلى المسارات المطلقة، أو ككائناتها الأم، أو كاسم خاصية العنصر الأصلي. إذا تم التعيين إلى "all"، فسيتم إرجاع كل هذه الأنواع على كائن مع النوع كاسم مفتاح.
• sandbox (الافتراضي: {}) - خريطة مفتاح-قيمة للمتغيرات المتاحة لتقييمات التعليمات البرمجية مثل تعبيرات التصفية. (لاحظ أن المسار الحالي والقيمة سيكونان متاحين أيضًا لتلك التعبيرات؛ راجع قسم Syntax للحصول على التفاصيل.)
• wrap (الافتراضي: true) - ما إذا كان سيتم تغليف النتائج في مصفوفة أم لا. إذا تم تعيين wrap إلى false، ولم يتم العثور على نتائج، فسيتم إرجاع undefined (على عكس مصفوفة فارغة عندما يتم تعيين wrap إلى true). إذا تم تعيين wrap إلى وتم العثور على نتيجة واحدة غير مصفوفة، فستكون تلك النتيجة هي العنصر الوحيد المُعاد (وليست داخل مصفوفة). ومع ذلك، سيتم إرجاع مصفوفة إذا تم العثور على نتائج متعددة. لتجنب الغموض (في الحالة التي يكون فيها من الضروري التمييز بين نتيجة فاشلة ونتيجة تمثل مصفوفة فارغة)، يُنصح بتغيير الافتراضي إلى .

طرق المثيل

• evaluate(path, json, callback, otherTypeCallback) أو evaluate({path: <path>, json: <json object>, callback: <callback function>, otherTypeCallback: <otherTypeCallback function>}) - هذه الطريقة ضرورية فقط إذا تم تعيين خاصية autostart إلى false. يمكن استخدامها لإجراء تقييمات متكررة باستخدام نفس الإعدادات. بالإضافة إلى الخصائص المذكورة، يمكن لنمط الطريقة الأخير قبول أي من خصائص المثيل الأخرى المسموح بها (باستثناء autostart الذي لا صلة له هنا).

خصائص وطرق الفئة

• JSONPath.clearCache() - يمسح المسارات المُحلَّلة والبرامج النصية المجمَّعة المخزَّنة مؤقتًا داخليًا. لا يتم كشف محتويات ذاكرة التخزين المؤقت؛ استدعِ هذه الطريقة عندما تكون هناك حاجة إلى إبطال ذاكرة التخزين المؤقت.
• JSONPath.toPathArray(pathAsString) - يقبل مسارًا معياريًا أو غير معياري كسلسلة نصية ويحوله إلى مصفوفة: على سبيل المثال، ['$', 'aProperty', 'anotherProperty'].
• JSONPath.toPathString(pathAsArray) - يقبل مصفوفة مسارات ويحوّلها إلى سلسلة مسار معيارية. ستكون السلسلة بصيغة مثل: $['aProperty']['anotherProperty][0]. الإنشاءات الطرفية لـ JSONPath مثل ~ و^ وعوامل التشغيل من النوع مثل @string() تتم إزالتها بصمت.
• JSONPath.toPointer(pathAsArray) - يقبل مصفوفة مسارات ويحوّلها إلى مؤشر JSON. ستكون السلسلة بصيغة مثل: /aProperty/anotherProperty/0 (مع تهريب أي أحرف داخلية ~ و/ وفقًا لمواصفات مؤشر JSON). الإنشاءات الطرفية لـ JSONPath مثل ~ و^ و عوامل التشغيل من النوع مثل تتم إزالتها بصمت.

الصياغة من خلال الأمثلة

بالنظر إلى JSON التالي، المأخوذ من http://goessner.net/articles/JsonPath/:```json { "store": { "book": [ { "category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95 }, { "category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99 }, { "category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99 }, { "category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99 } ], "bicycle": { "color": "red", "price": 19.95 } } }

والتمثيل التالي بصيغة XML:```xml
<store>
    <book>
        <category>reference</category>
        <author>Nigel Rees</author>
        <title>Sayings of the Century</title>
        <price>8.95</price>
    </book>
    <book>
        <category>fiction</category>
        <author>Evelyn Waugh</author>
        <title>Sword of Honour</title>
        <price>12.99</price>
    </book>
    <book>
        <category>fiction</category>
        <author>Herman Melville</author>
        <title>Moby Dick</title>
        <isbn>0-553-21311-3</isbn>
        <price>8.99</price>
    </book>
    <book>
        <category>fiction</category>
        <author>J. R. R. Tolkien</author>
        <title>The Lord of the Rings</title>
        <isbn>0-395-19395-8</isbn>
        <price>22.99</price>
    </book>
    <bicycle>
        <color>red</color>
        <price>19.95</price>
    </bicycle>
</store>

يرجى ملاحظة أن أمثلة XPath أدناه لا تميّز بين استرجاع العناصر ومحتواها النصي (إلا عندما يكون ذلك مفيدًا لـ إجراء المقارنات أو لمنع الغموض). ملاحظة: لاختبار أمثلة XPath (بما في ذلك إصدارات 2.0)، هذا العرض التوضيحي قد يكون مفيدًا (اضبطه على xml أو xml-strict).| XPath | JSONPath | النتيجة | ملاحظات | |-------------------------------------------------------------------------------------|---------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | /store/book/author | $.store.book[*].author | مؤلفو جميع الكتب في المتجر | يمكن أيضاً تمثيلها بدون $. على النحو store.book[*].author (على الرغم من أن هذا غير موجود في المواصفة الأصلية)؛ لاحظ أن بعض الحروف الحرفية ($ و@) تتطلب escape، ومع ذلك | | | | جميع المؤلفين | | | | | كل الأشياء في المتجر، وهي كتبه (مصفوفة كتب) ودراجة حمراء (كائن دراجة). | | | | | سعر كل شيء في المتجر. | | | | | الكتاب الثالث (كائن كتاب) | | | | | الكتاب الأخير بالترتيب. | للوصول إلى خاصية ذات حرف خاص، استخدم للفلتر (هذه الميزة بالذات غير موجودة في المواصفة الأصلية) | | | | أول كتابين | | | أو في XPath 2.0 | | تصنيفات ومؤلفو جميع الكتب | | | | | تصفية جميع الكتب التي تحتوي على رقم ISBN | للوصول إلى خاصية ذات حرف خاص، استخدم للفلتر (هذه الميزة بالذات غير موجودة في المواصفة الأصلية) | | | | تصفية جميع الكتب الأرخص من 10 | | | | | الحصول على جميع قيم الخصائص للكائنات التي تكون خاصيتها price ولا تساوي 8.95 | مع المجردة التي تسمح بتصفية الكائنات حسب قيمة الخاصية (وليس بالضرورة داخل المصفوفات)، يمكنك إضافة بعد التعبير للوصول إلى الكائن الذي يمتلك الخصائص التي تمت تصفيتها | | | | جذر كائن JSON (أي الكائن بأكمله نفسه) | للحصول على حرفية (بمفردها أو في أي مكان في المسار)، يجب استخدام escape بالعلامة الخلفية (backtick) | | | | جميع العناصر (والنصوص) تحت الجذر في مستند XML. جميع أعضاء بنية JSON تحت الجذر. | | | | | جميع العناصر في مستند XML. جميع المكونات الأصلية لبنية JSON بما في ذلك الجذر. | لم يتم تحديد هذا السلوك مباشرة في المواصفة الأصلية | | | | أصل تلك العناصر المحددة التي يزيد سعرها عن 19 (أي قيمة المتجر كأصل للدراجة ومصفوفة الكتب كأصل لكتاب فردي) | الأصل (علامة الإقحام ^) غير موجود في المواصفة الأصلية | | (في XPath 2.0) | | أسماء خصائص الكائن الفرعي للمتجر ("book" و"bicycle"). مفيدة مع خصائص wildcard. | اسم الخاصية (العلامة ~) غير موجود في المواصفة الأصلية | | (في XPath 2.0) | | جميع الكتب باستثناء ذلك الموجود في المسار الذي يشير إلى الأول | غير موجود في المواصفة الأصلية | | | | يلتقط جميع تصنيفات الكتب حيث يكون للكائن الأصل للكتاب عنصر فرعي دراجة بلون أحمر (أي جميع الكتب) | غير موجود في المواصفة الأصلية | | | | يلتقط جميع العناصر الفرعية لـ"book" باستثناء عناصر "category" | غير موجود في المواصفة الأصلية | | | | يلتقط جميع الكتب التي تكون خاصيتها (والتي، نظراً لأننا نصل داخل مصفوفة، هي الفهرس الرقمي) ليست 0 | غير موجود في المواصفة الأصلية | | | | يلتقط أحفاد المتجر الذين ليست خاصيتهم الأصلية book (أي أطفال الدراجة، "color" و"price") | غير موجود في المواصفة الأصلية | | | | الحصول على قيم الخصائص لجميع حالات الكتب حيث لا تكون الخاصية الأصلية لهذه القيم (أي فهرس المصفوفة الذي يحتوي على الكائن الأصل لعنصر الكتاب) هي 0 | غير موجود في المواصفة الأصلية | | | | تصفية جميع الكتب التي يساوي سعرها سعر الكتاب الثالث | غير موجود في المواصفة الأصلية | | (في XPath 2.0) | | الحصول على القيم الرقمية داخل مصفوفة الكتاب | ، والأنواع الأساسية الأخرى (، )، والأنواع المشتقة الأخرى منخفضة المستوى (، ، )، والنوع المضاف من JSONSchema، ، والنوع المركب (الذي يقبل أيضاً والأرقام غير المنتهية لكائنات JavaScript بالإضافة إلى جميع الأنواع الأساسية غير الكائنية/غير الدوالية)، والنوع ، الذي يُستخدم بالتزامن مع دالة استدعاء معرّفة من قبل المستخدم (انظر )، والأنواع التالية غير JSON التي يمكن مع ذلك استخدامها مع JSONPath عند الاستعلام عن كائنات JavaScript غير JSON (، ، ) غير موجودة في المواصفة الأصلية | | (XPath 2.0) | | جميع تصنيفات الكتب التي تطابق التعبير النمطي (تنتهي بـ'TION' دون حساسية لحالة الأحرف) | غير موجود في المواصفة الأصلية. | | (XPath 2.0) | | جميع الكتب التي لديها خاصية تطابق التعبير النمطي (تنتهي بـ'TION' دون حساسية لحالة الأحرف) | غير موجود في المواصفة الأصلية. ملاحظة: يستخدم محدد الأصل في نهاية التعبير للعودة إلى الكائن الأصل؛ بدون محدد الأصل، يطابق قيمتي مفتاح . | | | (على سبيل المثال، لمطابقة خاصية مسماة حرفياً ) | يهرب التسلسل بأكمله الذي يليها (ليُعامل كقيمة حرفية) | غير موجودة في المواصفة الأصلية؛ للحصول على backtick حرفية، استخدم backtick إضافية لعمل escape |أي متغيرات إضافية يتم توفيرها كخصائص على خيار الكائن الاختياري "sandbox" تكون متاحة أيضًا للتقييمات (المبنية على الأقواس).

مصادر الالتباس المحتملة لمستخدمي XPath

1. في JSONPath، تعبير التصفية، بالإضافة إلى كون @ مرجعًا لأبنائه، يقوم فعليًا بتحديد الأبناء المباشرين أيضًا، بينما في XPath، لا تحدد شروط التصفية الأبناء بل تحدد أيًّا من العقد الأصلية سيتم الحصول عليه في النتيجة.
2. في JSONPath، فهارس المصفوفات، كما في JavaScript، أساسها 0 (تبدأ من 0)، بينما في XPath، أساسها 1.
3. في JSONPath، تستخدم اختبارات المساواة (كما في JavaScript) علامات يساوي متعددة بينما في XPath، تُستخدم علامة يساوي واحدة.

واجهة سطر الأوامر

يتم توفير واجهة سطر أوامر (CLI) أساسية. يمكن الوصول إليها باستخدام npx jsonpath-plus <json-file> <jsonpath-query>.

أفكار

1. دعم OR خارج الفلاتر (كما في XPath |) والتجميع.
2. إنشاء صيغة تعمل مثل فلاتر XPath في عدم تحديد الأبناء؟
3. السماح بخيار يعادل parentNode (مع الحفاظ على السلسلة الكاملة من كائنات parent وparentProperty حتى الجذر)

التطوير

تشغيل الاختبارات على Node:```shell npm test

لإجراء الاختبارات داخل المتصفح:

- اخدم ملفات js/html:```shell
npm run browser-test

• قم بزيارة http://localhost:8082/test/.

الأمان

يُرجى مراجعة SECURITY.md للاطلاع على اعتبارات الأمان المهمة وتعليمات الإبلاغ عن الثغرات.

الترخيص

رخصة MIT.