jstachio__jstachio_CVE-2023-33962_1-0-0

محرك قوالب Mustache بلغة Java آمن من ناحية الأنواع.

تُترجم القوالب إلى كود مصدري Java قابل للقراءة، وتُفحص ارتباطات القيم بشكل ثابت.

Documentation

• أحدث وثائق JStachio (نسخة SNAPSHOT)
• وثائق JStachio الحالية المنشورة

الوثائق متاحة أيضًا على javadoc.io لكنها غير مجمّعة مثل ما سبق. الوثائق المجمّعة هي الوثائق المفضلة، وبقية هذا README مخصصة أساسًا لأغراض دعاية تسويقية.

للإصدارات السابقة:

https://jstach.io/doc/jstachio/VERSION/apidocs

حيث VERSION هو الإصدار الذي تريده.

لماذا تختار JStachio

مُغطى في why_jstachio_is_better.md.

الميزات

• صيغة Mustache (الإصدار 1.3) الخالية من المنطق.

  • دعم كامل للمتطلبات الإلزامية لمواصفة Mustache v1.3.0 (بما في ذلك المسافات البيضاء)
  • دعم اختياري للوراثة مع بعض التحفظات
  • دعم اختياري لـ lambda مع بعض الاختلافات بسبب الطبيعة الثابتة

• احصل على دعم شبيه بـ JEP 430 اليوم ولكن بقوة أكبر.

• تُترجم القوالب إلى كود Java

• ارتباطات القيم تُفحص بشكل ثابت.

• يمكن الإشارة إلى الطرق والحقول وطرق الوصول (getter-methods) في القوالب.

• رسائل خطأ ودية مع سياق.

• صفر إعدادات. لا حاجة إلى إضافات أو تعديلات. كل شيء يتم بواسطة javac القياسي مع أي IDE و/أو نظام بناء.

• تُدعم القوالب غير HTML. مجموعة أنواع المحتوى المدعومة للهروب (escaping) قابلة للتوسيع.

• تُدعم التخطيطات عبر مواصفة وراثة Mustache.

• نقطة تمديد لخدمة العرض الاحتياطية عبر ServiceLoader

  • التراجع بسلاسة إلى عرض وقت التشغيل القائم على الانعكاس عبر JMustache و mustache.java (مفيد للتطوير وتغيير القوالب في الوقت الفعلي)
  • إذا لم تكن من محبي الكود المُولَّد، فلا يزال بإمكانك استخدام JStachio للتحقق من أنواع قوالب mustache الخاصة بك.

• تخصيص الأنواع المسموح بإخراجها، وإلا خطأ في المترجم (لتجنب toString على الفئات التي لا تمتلك toString ودية).

• مُنسِّق لـ toString المخصص للمتغيرات في وقت التشغيل

• إضافة واجهات implements إضافية إلى الكود المُولَّد لإضافات شبيهة بالسمات (@JStacheInterfaces)

• دعم قوي لـ Lambda

• دعم Map<String, ?>

• دعم Optional<?>

• متوافق مع امتدادات فهرس القوائم في JMustache و Handlebars (مثل -first و -last و -index)

• إنه إلى حد بعيد أسرع محرك قوالب Java شبيه بـ Mustache، ومن الأسرع عمومًا.

• صفر تبعيات بخلاف JStachio نفسه

• يتوفر خيار بعدم وجود أي تبعيات وقت تشغيل إطلاقًا (أي أن كل الكود المطلوب يتم توليده ولا نحتاج حتى إلى jstachio أثناء وقت التشغيل). لا حاجة لاستخدام Maven shade لمعالجات التعليقات التوضيحية ومشاريع صفر التبعيات الأخرى. مفيد أيضًا لمشاريع Graal VM الأصلية لتحقيق أصغر مساحة ممكنة.

• دعم من الدرجة الأولى لإطار Spring Framework (بمعنى أن المشروع نفسه سيوفر الإضافات بدلاً من مشروع مساعد)

Performance

ليس هدف هذا المشروع أن يكون أسرع محرك قوالب Java!

_{^{(ومع ذلك، فهو حاليًا الأسرع الذي أعرفه عند آخر تحديث لهذا README)}}

ليس أن الأداء مهم كثيرًا مع لغات القوالب (ونادرًا ما يكون هو عنق الزجاجة) لكن JStachio سريع جدًا:

https://github.com/agentgt/template-benchmark

مخرجات نصية (String)

مخرجات بايت UTF-8 مع الأحرف الموسعة

مثال سريع

@JStache(template = """
        {{#people}}
        {{message}} {{name}}! You are {{#ageInfo}}{{age}}{{/ageInfo}} years old!
        {{#-last}}
        That is all for now!
        {{/-last}}
        {{/people}}
        """)
public record HelloWorld(String message, List<Person> people) implements AgeLambdaSupport {
}

public record Person(String name, LocalDate birthday) {
}

public record AgeInfo(long age, String date) {
}

public interface AgeLambdaSupport {

    @JStacheLambda
    default AgeInfo ageInfo(Person person) {
        long age = ChronoUnit.YEARS.between(person.birthday(), LocalDate.now());
        String date = person.birthday().format(DateTimeFormatter.ISO_DATE);
        return new AgeInfo(age, date);
    }

}

@Test
public void testPerson() throws Exception {
    Person rick = new Person("Rick", LocalDate.now().minusYears(70));
    Person morty = new Person("Morty", LocalDate.now().minusYears(14));
    Person beth = new Person("Beth", LocalDate.now().minusYears(35));
    Person jerry = new Person("Jerry", LocalDate.now().minusYears(35));
    String actual = JStachio.render(new HelloWorld("Hello alien", List.of(rick, morty, beth, jerry)));
    String expected = """
            Hello alien Rick! You are 70 years old!
            Hello alien Morty! You are 14 years old!
            Hello alien Beth! You are 35 years old!
            Hello alien Jerry! You are 35 years old!
            That is all for now!
                            """;
    assertEquals(expected, actual);

}

التثبيت

Maven

<properties>
    <io.jstach.version>0.6.0-SNAPSHOT</io.jstach.version>
</properties>
...
<dependencies>
    <dependency>
        <groupId>io.jstach</groupId>
        <artifactId>jstachio</artifactId>
        <version>${io.jstach.version}</version>
    </dependency>
</dependencies>
...
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <source>17</source> <!-- 17 is the minimum -->
                <target>17</target> <!-- 17 is the minimum -->
                <annotationProcessorPaths>
                    <path>
                        <groupId>io.jstach</groupId>
                        <artifactId>jstachio-apt</artifactId>
                        <version>${io.jstach.version}</version>
                    </path>
                    <!-- other annotation processors -->
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

ملاحظة: يتم جلب jar التعليقات التوضيحية (jstachio-annotation) بشكل غير مباشر.

Gradle

dependencies {
 
    implementation 'io.jstach:jstachio:VERSION'
 
    annotationProcessor 'io.jstach:jstachio-apt:VERSION'
}

أمثلة

user.mustache

{{#name}}
<p>Name: {{.}}, Name Length is {{length}}</p>
{{/name}}

<p>Age: {{  age  }}</p>

<p>Achievements:</p>

<ul>
{{#array}}
  <li>{{.}}</li>
{{/array}}
</ul>

{{^array}}
<p>No achievements</p>
{{/array}}

<p>Items:</p>

<ol>
{{#list1}}
  <li>{{value}}</li>
{{/list1}}
</ol>

User.java

يمكن استخدام الفئة التالية لتوفير البيانات الفعلية لتعبئة القالب أعلاه.

@JStache(
    // points to src/main/resources/user.mustache file
    path = "user.mustache",
   
    // or alternatively you can inline the template
    template = "", 

    )
public record User(String name, int age, String[] array, List<Item<String>> list) {

   public static class Item<T> {
        private final T value;
        public Item(T value) {
            this.value = value;
        }
        T value() {
            return value;
        }
    }
}

العرض