Постановка задачи

<TreatWarningsAsErrors>true</TreatWarningsAsErrors><Nullable>enable</Nullable>

    public sealed class SomeClient    {        private readonly SomeClientOptions options;        public SomeClient(SomeClientOptions options)        {            this.options = options;        }        public void SendSomeRequest()        {            Console.WriteLine($"Do work with { this.options.Login.ToLower() }" +                $" and { this.options.CertificatePath.ToLower() }");        }    }

    public sealed class SomeClientOptions    {        public string Login { get; set; }        public string CertificatePath { get; set; }        public SomeClientOptions(string login, string certificatePath)        {            Login = login;            CertificatePath = certificatePath;        }    }

{  "SomeClientOptions": {    "Login": "ferzisdis",    "CertificatePath":  ".\full_access.pfx"  }}

Наивная попытка использовать встроенные инструменты

    public class Startup    {        public Startup(IConfiguration configuration)        {            Configuration = configuration;        }        public IConfiguration Configuration { get; }        public void ConfigureServices(IServiceCollection services)        {            var options = Configuration.GetSection(nameof(SomeClientOptions)).Get<SomeClientOptions>();            services.AddSingleton(options);        }    }

public sealed class SomeClientOptions    {        private string login = null!;        private string certificatePath = null!;        public string Login        {            get            {                return login;            }            set            {                login = !string.IsNullOrEmpty(value) ? value : throw new InvalidOperationException($"{nameof(Login)} cannot be null!");            }        }        public string CertificatePath        {            get            {                return certificatePath;            }            set            {                certificatePath = !string.IsNullOrEmpty(value) ? value : throw new InvalidOperationException($"{nameof(CertificatePath)} cannot be null!");            }        }    }

Альтернативы получше

    public sealed class SomeClientOptionsRaw    {        public string? Login { get; set; }        public string? CertificatePath { get; set; }    }    public sealed class SomeClientOptions : ISomeClientOptions    {        private readonly SomeClientOptionsRaw raw;        public SomeClientOptions(SomeClientOptionsRaw raw)        {            this.raw = raw;        }        public string Login            => !string.IsNullOrEmpty(this.raw.Login) ? this.raw.Login : throw new InvalidOperationException($"{nameof(Login)} cannot be null!");        public string CertificatePath            => !string.IsNullOrEmpty(this.raw.CertificatePath) ? this.raw.CertificatePath : throw new InvalidOperationException($"{nameof(CertificatePath)} cannot be null!");    }    public interface ISomeClientOptions    {        public string Login { get; }        public string CertificatePath { get; }    }

    public sealed class SomeClientOptions : ISomeClientOptions    {        private readonly IConfiguration configuration;        public SomeClientOptions(IConfiguration configuration)        {            this.configuration = configuration;        }        public string Login => GetNotNullValue(nameof(Login));        public string CertificatePath => GetNotNullValue(nameof(CertificatePath));        private string GetNotNullValue(string propertyName)        {            var value = configuration[$"{nameof(SomeClientOptions)}:{propertyName}"];            return !string.IsNullOrEmpty(value) ? value : throw new InvalidOperationException($"{propertyName} cannot be null!");        }    }

Как не писать руками лишний код?

1. Создается runtime реализация интерфейса
2. Выполняется десериализация объекта стандартными средствами
3. Выполняется проверка свойств на null (проверяются только те свойста, которые отмечены как NotNull)

    public static class ConfigurationExtensions    {        private static readonly InterfaceImplementationBuilder InterfaceImplementationBuilder = new InterfaceImplementationBuilder();        private static readonly NullReferenceValidator NullReferenceValidator = new NullReferenceValidator();        public static T GetOptions<T>(this IConfiguration configuration, string sectionName)        {            var implementationOfInterface = InterfaceImplementationBuilder.BuildClass<T>();            var options = configuration.GetSection(sectionName).Get(implementationOfInterface);            NullReferenceValidator.CheckNotNullProperties<T>(options);            return (T) options;        }    }

    public sealed class InterfaceImplementationBuilder    {        private readonly Lazy<ModuleBuilder> _module;        public InterfaceImplementationBuilder()        {            _module = new Lazy<ModuleBuilder>(() => AssemblyBuilder                .DefineDynamicAssembly(new AssemblyName(Guid.NewGuid().ToString()), AssemblyBuilderAccess.Run)                .DefineDynamicModule("MainModule"));        }        public Type BuildClass<TInterface>()        {            return BuildClass(typeof(TInterface));        }        public Type BuildClass(Type implementingInterface)        {            if (!implementingInterface.IsInterface)            {                throw new InvalidOperationException("Only interface is supported");            }            var typeBuilder = DefineNewType(implementingInterface.Name);            ImplementInterface(typeBuilder, implementingInterface);            return typeBuilder.CreateType() ?? throw new InvalidOperationException("Cannot build type!");        }        private void ImplementInterface(TypeBuilder typeBuilder, Type implementingInterface)        {            foreach (var propertyInfo in implementingInterface.GetProperties())            {                DefineNewProperty(typeBuilder, propertyInfo.Name, propertyInfo.PropertyType);            }                        typeBuilder.AddInterfaceImplementation(implementingInterface);        }           private TypeBuilder DefineNewType(string baseName)        {            return _module.Value.DefineType($"{baseName}_{Guid.NewGuid():N}");        }        private static void DefineNewProperty(TypeBuilder typeBuilder, string propertyName, Type propertyType)        {            FieldBuilder fieldBuilder = typeBuilder.DefineField("_" + propertyName, propertyType, FieldAttributes.Private);            PropertyBuilder propertyBuilder = typeBuilder.DefineProperty(propertyName, PropertyAttributes.HasDefault, propertyType, null);            MethodBuilder getPropMthdBldr = typeBuilder.DefineMethod("get_" + propertyName, MethodAttributes.Public | MethodAttributes.SpecialName | MethodAttributes.HideBySig | MethodAttributes.Virtual, propertyType, Type.EmptyTypes);            ILGenerator getIl = getPropMthdBldr.GetILGenerator();            getIl.Emit(OpCodes.Ldarg_0);            getIl.Emit(OpCodes.Ldfld, fieldBuilder);            getIl.Emit(OpCodes.Ret);            MethodBuilder setPropMthdBldr =                typeBuilder.DefineMethod("set_" + propertyName,                    MethodAttributes.Public                    | MethodAttributes.SpecialName                    | MethodAttributes.HideBySig                    | MethodAttributes.Virtual,                    null, new[] { propertyType });            ILGenerator setIl = setPropMthdBldr.GetILGenerator();            Label modifyProperty = setIl.DefineLabel();            Label exitSet = setIl.DefineLabel();            setIl.MarkLabel(modifyProperty);            setIl.Emit(OpCodes.Ldarg_0);            setIl.Emit(OpCodes.Ldarg_1);            setIl.Emit(OpCodes.Stfld, fieldBuilder);            setIl.Emit(OpCodes.Nop);            setIl.MarkLabel(exitSet);            setIl.Emit(OpCodes.Ret);            propertyBuilder.SetGetMethod(getPropMthdBldr);            propertyBuilder.SetSetMethod(setPropMthdBldr);        }    }

    public sealed class NullReferenceValidator    {        public void CheckNotNullProperties<TInterface>(object options)        {            var propertyInfos = typeof(TInterface).GetProperties();            foreach (var propertyInfo in propertyInfos)            {                if (propertyInfo.PropertyType.IsValueType)                {                    continue;                }                if (!IsNullable(propertyInfo) && IsNull(propertyInfo, options))                {                    throw new InvalidOperationException($"Property {propertyInfo.Name} cannot be null!");                }            }        }        private bool IsNull(PropertyInfo propertyInfo, object obj)        {            var value = propertyInfo.GetValue(obj);            switch (value)            {                case string s: return string.IsNullOrEmpty(s);                default: return value == null;            }        }        // https://stackoverflow.com/questions/58453972/how-to-use-net-reflection-to-check-for-nullable-reference-type        private bool IsNullable(PropertyInfo property)        {            if (property.PropertyType.IsValueType)            {                throw new ArgumentException("Property must be a reference type", nameof(property));            }            var nullable = property.CustomAttributes                .FirstOrDefault(x => x.AttributeType.FullName == "System.Runtime.CompilerServices.NullableAttribute");            if (nullable != null && nullable.ConstructorArguments.Count == 1)            {                var attributeArgument = nullable.ConstructorArguments[0];                if (attributeArgument.ArgumentType == typeof(byte[]) && attributeArgument.Value != null)                {                    var args = (ReadOnlyCollection<CustomAttributeTypedArgument>)attributeArgument.Value;                    if (args.Count > 0 && args[0].ArgumentType == typeof(byte))                    {                        return (byte)args[0].Value == 2;                    }                }                else if (attributeArgument.ArgumentType == typeof(byte))                {                    return (byte)attributeArgument.Value == 2;                }            }            var context = property.DeclaringType.CustomAttributes                .FirstOrDefault(x => x.AttributeType.FullName == "System.Runtime.CompilerServices.NullableContextAttribute");            if (context != null &&                context.ConstructorArguments.Count == 1 &&                context.ConstructorArguments[0].ArgumentType == typeof(byte) &&                context.ConstructorArguments[0].Value != null)            {                return (byte)context.ConstructorArguments[0].Value == 2;            }            // Couldn't find a suitable attribute            return false;        }    }

    public class Startup    {        public Startup(IConfiguration configuration)        {            Configuration = configuration;        }        public IConfiguration Configuration { get; }        public void ConfigureServices(IServiceCollection services)        {            var options = Configuration.GetOptions<ISomeClientOptions>("SomeClientOptions");            services.AddSingleton(options);        }    }

Заключение

Недавно, когда я просматривал новые возможности, которые будут включены в .Net 5, я натолкнулся на одну весьма интересную генераторы исходного кода. Этот функционал меня особенно заинтересовал, так как я использую аналогичный подход в течение последних 5 лет, и то, что предлагает Microsoft это просто более глубокая интеграция этого подхода в процесс сборки проектов.

Примечание: Оригинал был написан в момент, когда релиз .Net 5 только-только собирался выйти, но актуальности этот текст, на мой взгляд, не потерял, поскольку переход на новую версию платформы занимает какое-то время, да и принципы работы с Roslyn никак не поменялись.

Далее я поделюсь своим опытом использования Roslyn при генерации кода, и надеюсь, что это поможет вам лучше понять, что именно предлагает Microsoft в .Net 5 и в каких случаях это можно использовать.

Для начала, давайте рассмотрим типичный сценарий генерации исходного кода. У вас есть некий внешний источник информации например такой как база данных или JSON описание какого-нибудь REST сервиса или другая .Net сборка (через рефлексию) или что-нибудь еще, и с помощью этой информации вы можете сгенерировать различные типы исходного кода, такие как DTO, классы моделей базы данных или прокси для REST сервисов.

Однако иногда возникают ситуации, когда нет какого-либо внешнего источника информации и все, что вам нужно, содержится в исходном коде самого проекта, куда вы хотите добавить какой-то сгенерированный код.

По совпадению, я недавно опубликовал проект с открытым исходным кодом, в котором есть пример такой ситуации. В проекте более 100 классов, которые представляют узлы синтаксического дерева SQL, и мне нужно было создать посетителей (visitors реализации интерфейса IVisitor в советующем шаблоне проектирования), которые будут обходить и изменять объекты дерева (больше информации о проекте вы можете найти в моей предыдущей статье "Дерево синтаксиса и альтернатива LINQ при взаимодействии с базами данных SQL").

Причина, по которой генерация кода является здесь хорошим выбором, заключается в том, что каждый раз, когда я делаю даже небольшое изменение в классах, мне нужно помнить об изменении посетителей (visitors), и эти изменения должны выполняться очень осторожно. Однако я не могу использовать рефлексию для генерации кода, так как сборка (assembly), которая содержит эти новые изменения, просто еще не существует, и если эти изменения несовместимы с предыдущей версией и приводят к ошибкам компиляции, то эта сборка никогда и не появится до тех пор, пока я вручную не исправлю все ошибки.

На первый взгляд, у этой проблемы нет решения, но на самом деле, чтобы её решить, я могу использовать компилятор Roslyn и заранее пре-компилировать классы модели, получив таким образом информацию, аналогичную той, которую я мог бы получить через рефлексию.

Давайте создадим простое консольное приложение и добавим в него пакет Microsoft.CodeAnalysis.CSharp.

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

Для начала, нам нужно прочитать все .cs файлы, содержащие классы модели, и извлечь из них синтаксические деревья:

var files = Directory.EnumerateFiles(    Path.Combine(projectFolder, "Syntax"),     "*.cs",     SearchOption.AllDirectories);files = files.Concat(Directory.EnumerateFiles(projectFolder, "IExpr*.cs"));var trees = files    .Select(f => CSharpSyntaxTree.ParseText(File.ReadAllText(f)))    .ToList();

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

var cSharpCompilation = CSharpCompilation.Create("Syntax", trees);foreach (var tree in trees){    var semantic = cSharpCompilation.GetSemanticModel(tree);    ...

Используя семантические данные, мы можем получить объект типа INamedTypeSymbol:

foreach (var classDeclarationSyntax in tree    .GetRoot()    .DescendantNodesAndSelf()    .OfType<ClassDeclarationSyntax>()){    var classSymbol = semantic.GetDeclaredSymbol(classDeclarationSyntax);

который может предоставить информацию о конструкторах и свойствах классов:

//Propertiesvar properties = GetProperties(classSymbol);List<ISymbol> GetProperties(INamedTypeSymbol symbol){    List<ISymbol> result = new List<ISymbol>();    while (symbol != null)    {        result.AddRange(symbol.GetMembers()            .Where(m => m.Kind == SymbolKind.Property));        symbol = symbol.BaseType;    }    return result;}//Constructorsforeach (var constructor in classSymbol.Constructors){    ...}

Поскольку все классы модели неизменяемы, то все значения свойств этих классов должны быть установлены через их конструкторы, поэтому переберем все параметры конструкторов и получим их типы:

foreach (var parameter in constructor.Parameters){    ...    INamedTypeSymbol pType = (INamedTypeSymbol)parameter.Type;

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

1. Является ли этот тип списком?
2. Является ли тип Nullable (в проекте используются "Nullable reference types")?
3. Наследуется ли от этот тип от базового типа (в нашем случае интерфейса), для которого мы и создаем "Посетителей" (Visitors).

Семантическая модель дает ответы на эти вопросы:

var ta = AnalyzeSymbol(ref pType);....(bool IsNullable, bool IsList, bool Expr) AnalyzeSymbol(    ref INamedTypeSymbol typeSymbol){    bool isList = false;    var nullable = typeSymbol.NullableAnnotation == NullableAnnotation.Annotated;    if (nullable && typeSymbol.Name == "Nullable")    {        typeSymbol = (INamedTypeSymbol)typeSymbol.TypeArguments.Single();    }    if (typeSymbol.IsGenericType)    {        if (typeSymbol.Name.Contains("List"))        {            isList = true;        }        if (typeSymbol.Name == "Nullable")        {            nullable = true;        }        typeSymbol = (INamedTypeSymbol)typeSymbol.TypeArguments.Single();    }    return (nullable, isList, IsExpr(typeSymbol));}

Примечание: метод AnalyzeSymbol извлекает фактический тип из коллекций и значений Nullables::

List<T> => T (list := true) T? => T (nullable := true) List<T>? => T (list := true, nullable := true)

Проверка базового типа в семантической модели Roslyn является более сложной задачей, чем такая же при использовании рефлексии, но это также возможно:

bool IsExpr(INamedTypeSymbol symbol){    while (symbol != null)    {        if (symbol.Interfaces.Any(NameIsExpr))        {            return true;        }        symbol = symbol.BaseType;    }    return false;    bool NameIsExpr(INamedTypeSymbol iSym)    {        if (iSym.Name == "IExpr")        {            return true;        }        return IsExpr(iSym);    }}

Теперь мы можем поместить всю эту информацию в простой контейнер:

public class NodeModel{    ...    public string TypeName { get; }    public bool IsSingleton { get; }    public IReadOnlyList<SubNodeModel> SubNodes { get; }    public IReadOnlyList<SubNodeModel> Properties { get; }}public class SubNodeModel{    ...    public string PropertyName { get; }    public string ConstructorArgumentName { get; }    public string PropertyType { get; }    public bool IsList { get; }    public bool IsNullable { get; }}

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

В моем проекте я запускаю генерацию кода как консольную утилиту, но в .Net 5 вы сможете встроить эту генерацию в класс реализующий интерфейс ISourceGenerator и помеченный специальным атрибутом Generator. Экземпляр этого класса будет автоматически создаваться и запускаться во время сборки проекта для добавления недостающих частей кода. Это, конечно, удобнее, чем отдельная утилита, но идея аналогична.

Примечание: Я здесь не буду описывать саму кодогенерацию в .Net 5 так как в интернете есть много информации об этом, например ссылка 1 или ссылка 2

В завершение, я хочу сказать, что вы не должны воспринимать эту новую возможность .Net 5 как невероятное нововведение, которое коренным образом изменит подход к генерации динамического кода, используемый в таких библиотеках, как AutoMapper, Dapper и т. д. (слышал и такие мнения) Не изменит! Дело в том, что описанная выше генерация кода работает в статическом контексте, где все заранее известно, но, например, AutoMapper не знает заранее, с какими классами он будет работать, и ему все равно придется динамически генерировать IL код "на лету". Однако бывают ситуации, когда такая генерация кода может быть весьма полезна (одну из них ситуаций я описал в этой статье). Поэтому стоит, как минимум, знать об этой возможности и понимать ее принципы и ограничения.

Ссылка на исходный код на github

Причины и проблемы, которые нужно было решить

В этой статье я вам расскажу о том как я писал кодогенератор на php. Расскажу о пути, который он прошел от генерации простых таблиц, до довольно полноценного генератора html и css кода. Приведу примеры его использования и покажу уже сделанные проекты.

В этом семестре на одном из предметов можно было использовать только PHP.

После бесконеного ренейма проекта Проект получил имя MelonPHP. Чтобы люди думали о еде когда произносили его имя? Но у нас тут статья не о генерации бреда, по этому давайте я вам расскажу о причине его создания.

Написать надо было много, но это не проблема. Основная проблема заключалась в выводе HTML кода через PHP. Я постараюсь объяснить проблему ниже.

Например вот вывод текста через всем знакомое echo:

$text = "out text";echo "<p>$text</p>";

Выглядит просто и понятно. Давайте возьмем отрезок кода моего друга, где он генерирует таблицу:

...$sql = "SELECT * FROM table";$result = $conn->query($sql);if($result->num_rows > 0) {    echo "<b>Table table</b><br><br>";    echo "<table border=2>";  echo "<tr><td> name </td>"."<td> name </td>"."<td> name </td></tr>";    while($row = $result->fetch_assoc()) {        echo "<tr><td>".$row["name"]."</td><td>".$row["name"]."</td><td>".$row["name"]."</td></tr>";    }    echo "</table>";} else {echo "0 results";}...

Это страшный код демонстрирует проблемы, которые я хотел решить:

• Присутствие html в php коде, что делает его по моему мнению менее читаемым. Все-таки файл для одного яп должен содержать код только одного яп(а), по моему мнению
• Нет разделения логики, все в каше. Хотелось более приятный "фронтенд" на PHP

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

Я был уверен, что быстрее будет написать небольшой кодогенератор, чем терпеть это.

Изначально генератор занимался генерацией таблиц через функции. Но потом перерос в ней-то более масштабное.

Основными идеями были следующими:

• UI пишется из элементов/компонентов (привет React)
• Удобные макеты (Избавиться от div, div, div, div...)
• Чтобы весь UI писался на PHP (без JS, без HTML, без CSS).
• Rebuild через callback события, через AJAX + JQuery не суждено
• Удобная система роутов не суждено
• Поддержка CSS (и не просто строку писать, на уровне "width: 100px", а полноценная поддержка прямо в PHP коде)
• ООП

Особенности MelonPHP

• Почти все элементы (кроме текста, кнопки и еще нескольких) по умолчанию имеют ширину и высоту в 100%, в том числе и документ.
• Кроме того, если элементы будут выходить за пределы страницы, то скролла по умолчанию не будет. Для этого нужно использовать ScrollView.
• Так же по умолчанию нельзя выделать никакие элементы.

Архитектура

Очень печально, что в PHP отсутствует передачу параметров по имени, и по этому я решил использовать вместо них функции. Я уверен что это не менее удобный аналог (Какого было мое удивление, когда Microsoft показали MAUI, который использует ту же идею с функциями).

Все классы в MelonPHP наследуется от Node. Это простой класс, который имеет только 2 функции: Generate(), static Create().

• Generate() возвращает string сгенерированный код.
• Create() это статическая функция. Она нужна чтобы было проще создавать ноды в дереве.

abstract class Node{  abstract function Generate() : string;  static function Create() ...}

Element

Element это более высокоуровневый класс, который нужен для более комфортного написания своих элементов.

Элемент в основном занимается генерацией чистого html кода.

Элементами в Фреймворк являются такие сущности как контейнер, кнопка, таблица и тд.

Component

Основная идея компонента в том, что этот класс управляет, и состоит из дерева элементов в нем. Компонент наследуется от элемента (бредовая идея).

Компонентами могут быть например дисплеи (аналог страниц в MelonPHP), списки, карточки, навигационные меню и тд.

abstract class Component extends Element{  function Initialize() ...  abstract function Build() : Element;  function Detach() ...}

Компонент удобен тем что вам не надо генерировать строки, чем занимается Element, так же в нем есть удобные функции для использования логики.

Попробуем написать простой компонент. Создадим класс ListItem наследуемый от Component.

Перезапишем функции Initialize() и Build().

Initialize() вызывается при создание компонента. В ней например можно инициализировать переменные или обработать логику.

Build() вызывается при генерации элемента. В ней обязательно должен возвращаться элемент. Обязательная для перезаписи.

Detach() вызывается при удалении компонента.

В Build() возвратим контейнер, а в качестве его ребенка, элемент текста и присвоим ему текст из переменной класса $Text.

В Initialize() пропишем значение $Text по умолчанию.

Добавим функцию Text(string) в которой будет записываться значение пользователя в переменную $Text.

Обязательно надо возвращать $this в функциях, которые будут вызываться в дереве.

class ListItem extends Component{  private $Text;  function Initialize() {    $this->Text = "Name";  }  function Build() : Element {    return Container::Create()    ->Child(      Text::Create()      ->Text($this->Text)    );  }  function Text(string $string) {    $this->Text = $string;    return $this;  }}

DisplayComponent

DisplayComponent это компонент, который может выводит сгенерированный код на страницу. Для генерации нужно вызвать функцию Display.

Попробуем написать пример простого дисплея.

В функции Build() возвратим Document и присваиваем ему Title(string).

В DisplayComponent, в функции Build() всегда должен возвращаться Document. Document это класс, который генерирует стандартную разметку HTML5.

Создадим функцию BuildList(), в которой через цикл заполним колонку созданными выше ListItem.

В качестве ребенка документа вызовем BuildList() функцию. Разделение дерева из нод на функции не дает ему превратиться в макаронного монстра.

Если будет ситуация что надо выполнить какую-то логику прямо в дереве, то для того есть класс Builder. Но так лучше не делать...

После тела класса вызовем функцию Diplay(), которая при переходе на данный файл, на сайте cгенерирует его и выведит.

class ListDisplay extends DisplayComponent{  function Build() : Document {    return Document::Create()    // название страницы    ->Title("test page")    ->Child($this->BuildList());  }  function BuildList() {    $column = new Column;    for($i = 0; $i < 10; $i++)      $column->Children(        ListItem::Create()        ->Text("number: $i")      );    return $column;  }} ListDisplay::Display();

Макеты

Одна из целей преследуемых при создании фреймворка удобство при создание макетов сайта.

Container

Container это макет, который используется для декоративных целей.

Может содержать только одного ребенка.

Column и Row

У большинства элементов есть дети. Если у элемента доступен метод Child то он может иметь только одного ребенка, а если Children то у него может быть больше одного ребенка.

Так же Child перезаписывает переменную ребенка в то время как Children добавляет аргументы в верх стека.

В Children если один элемент в аргументе то не обязательно его заносить в массив.

Тоесть вместо Children([Text::Create()]) можно написать Children(Text::Create())

Column это макет который выравнивает его детей вертикально.

Обращаясь к функциям CrossAlign и MainAlign можно выравнивать детей внутри колонки.

Row идентичен Column, но выравнивает детей горизонтально.

Stack

Stack это макет дети которого не позиционированы. Это полезно если вы хотите чтобы ноды пересекались, для создания более красивого дизайна.

ScrollView, HorizontalScrollView, VerticalScrollView

Эти контейнеры который является областью для скороллинга.

HorizontalScrollView в этом контейнере можно скроллить только по горизонтальной оси.

VerticalScrollView в этом контейнере можно скроллить только по вертикальной оси.

ScrollView в этом контейнере можно скроллить по всем осям.

Стилизация

Долга думая как лучше встроить css в фреймворк я пришел к идее с константами.

Например у нас в css есть background-color. Я строку записываю в константу и в php коде можно будет использовать без "". Это намного удобнее.

...const BackgroundBlendMode = "background-blend-mode";const BackgroundAttachment = "background-attachment";const Border = "border";const BorderSpacing = "border-spacing";const BorderRadius = "border-radius";const BorderImage = "border-image";...

Что качается например такой конструкции "34".Px. Тут идея с константами выглядит не читабельно. По этому я решил в таких ситуациях использовать функции для css например Px(34). Выглядит понятно и вписывается в пхп код.

Простая стилизация

Для простой стилизации в элементе функция ThemeParameter(...). Первый аргумент это название параметра, а второй аргумент это или массив из значений/значение.

Рассмотрим пример.

В первом параметре мы изменим цвет фона на #f0f0f0.

В втором параметре мы добавим отступы. Сверху и снизу 20px, справа и слева 15px.

Значения в массиве генерируются через пробел. Если вы хотите чтобы генерация происходила через запятую, то для етого есть функция CommaLine().

...Container::Create()->ThemeParameter(BackgroundColor, Hex("f0f0f0"))->ThemeParameter(Padding, [Px(20), Px(15)]);...

Как видно все очень просто и удобно, но если нам понадобятся модификаторы (hover например)? Для этого сделаны темы.

Темы

Темы в этом Фреймворк это более продвинутый css, с media, keyframes, и модификаторами.

Напишем тему для контейнера с модификатором hover и active.

Для того надо создать класс темы и добавить в него ThemeBlock через метод ThemeBlocks.

Блоку темы нужно присвоить ключ / ключи. Я назову ключ my_container.

Дальше в блок темы можно добавить модификаторы. Я добавил: StandartModifier, HoverModifier, ActiveModifier. И задал для них параметры тебя через метод Parameter(...). Parameter работает так же как ThemeParameter.

function GetMyTheme() : Theme {  return Theme::Create()  ->ThemeBlocks([    ThemeBlock::Create()    ->Keys("my_container")    ->Modifiers([      StandartModifier::Create()      ->Parameter(BackgroundColor, Red)      ->Parameter(Padding, [Px(10), Px(12)]),      HoverModifier::Create()      ->Parameter(BackgroundColor, Green),      ActiveModifier::Create()      ->Parameter(BackgroundColor, Blue)    ])  ]);}

Дальше контейнеру я присвоил ключ (имя класса в css) темы через метод ThemeKeys. Но для того чтобы тему можно было использовать ее надо добавить в документ через метод Themes.

class TestThemeDisplay extends DisplayComponent{  function Build() : Document {    return Document::Create()    ->Themes(GetMyTheme())    ->Child(      Container::Create()      ->ThemeKeys("my_container")    );  }} TestThemeDisplay::Display();

После можно запустить дисплей и увидеть что тема по ключу применилась.

Продвинутые анимации

Для продвинутой анимации есть keyframes.

Для того чтобы добавить в тему keyframe, используйте метод FrameBlocks.

Добавим уже в существующую тему FrameBlock.

В FrameBlock есть метод Frames. Вызовем его и добавим несколько фреймов, так же для каждого фрейма надо указывать Value. Оно может быть в процентах (используйте функцию Pr(value)) или может быть константа From, To.

Каждому кадру можно добавлять параметры которые будут уникальны и плавно изменятся между другими кадрами.

Так же добавим блок темы в котором будет применяться эта анимация и назовем его shake_text.

Создадим текст в предыдущем дисплее, в контейнере и применим ему ключ темы.

Так же на примере видно что в параметре можно использовать и обычные строки.

function GetMyTheme() : Theme {  return Theme::Create()  ->ThemeBlocks([    ThemeBlock::Create()    ->Keys("my_container")    ->Modifiers([      StandartModifier::Create()      ->Parameter(Padding, [Px(10), Px(12)]),      HoverModifier::Create()      ->Parameter(BackgroundColor, Green),      ActiveModifier::Create()      ->Parameter(BackgroundColor, Blue)    ]),    ThemeBlock::Create()    ->Keys("shake_text")    ->Modifiers([      StandartModifier::Create()      ->Parameter(Color, Red)      ->Parameter(Animation, ["shake_text_anim", ".2s", "ease-in-out", "5", "alternate-reverse"])    ])  ])  ->FrameBlocks(    FrameBlock::Create()    ->Key("shake_text_anim")    ->Frames([      Frame::Create()      ->Value(Pr(0))      ->Parameter(Transform, Translate(0, 0)),      Frame::Create()      ->Value(Pr(25))      ->Parameter(Color, Hex("ff4040"))      ->Parameter(Filter, Blur(Px(0.5))),      Frame::Create()      ->Value(Pr(50))      ->Parameter(Filter, Blur(Px(1.2))),      Frame::Create()      ->Value(Pr(75))      ->Parameter(Color, Hex("ff4040"))      ->Parameter(Filter, Blur(Px(0.5))),      Frame::Create()      ->Value(Pr(100))      ->Parameter(Transform, Translate(Px(10), 0)),    ])  );}

class TestThemeDisplay extends DisplayComponent{  function Build() : Document {    return Document::Create()    ->Themes(GetMyTheme())    ->Child(      Container::Create()      ->ThemeKeys("my_container")      ->Child(        Text::Create()        ->ThemeKeys("shake_text")        ->Text("Error text")      )    );  }} TestThemeDisplay::Display();

Адаптивность

Создадим еще 2 темы. Одна будет для мобильных девайсов, а вторая для пк. У темы есть функции: MinWidth, MaxWidth, MinHeight, MaxHeight, объявив которые вы можете указать на каком размере будет работать тема.

Теме для телефонов зададим MinWidth 800px.

Теме для пк зададим MaxWidth 800px.

Создадим блок темы где в стандартном модификаторе для мобильной версии будет присваиваться цвет фона зелёный, а на пк версии желтый. Назовем блок adaptive_color.

Добавим обе темы в документ дисплея.

Добавим ключи темы к контейнеру.

function GetMobileTheme() : Theme {  return Theme::Create()  ->MinWidth(Px(800))  ->ThemeBlocks(    ThemeBlock::Create()    ->Keys("adaptive_color")    ->Modifiers(      StandartModifier::Create()      ->Parameter(BackgroundColor, Green)    )  );}

function GetDesktopTheme() : Theme {  return Theme::Create()  ->MaxWidth(Px(800))  ->ThemeBlocks(    ThemeBlock::Create()    ->Keys("adaptive_color")    ->Modifiers(      StandartModifier::Create()      ->Parameter(BackgroundColor, Red)    )  );}

class TestThemeDisplay extends DisplayComponent{  function Build() : Document {    return Document::Create()    ->Themes([      GetMyTheme(),       GetDesktopTheme(),       GetMobileTheme()    ])    ->Child(      Container::Create()      ->ThemeKeys(["my_container", "adaptive_color"])      ->Child(        Text::Create()        ->ThemeKeys("shake_text")        ->Text("Error text")      )    );  }} TestThemeDisplay::Display();

Логика

Попробуем написать простой кликер.

Для начала нам надо создать класс и наследовать его от DisplayComponent.

Создадим функцию Build() и возвратим в ней Document.

class ClickerDisplay extends DisplayComponent{  function Build() : Element {    return Document::Create()    ->Title("Clicker");   }} ClickerDisplay::Display();

Добавим колонку в качестве ребенка документа.

Так же в качестве детей колонки добавим текст и кнопку.

class ClickerDisplay extends DisplayComponent{  function Build() : Element {    return Document::Create()    ->Title("Clicker")    ->Child(      Column::Create()      ->Children([        Text::Create()        ->Text("Pressed 0 times"),        Button::Create()        ->Text("Press")      ])    );   }} ClickerDisplay::Display();

Результат будет следующим.

Далее добавим простые ThemeParameter, чтобы сделать наш пример красивее.

class ClickerDisplay extends DisplayComponent{  function Build() : Element {    return Document::Create()    ->Title("Clicker")    ->Child(      Column::Create()      ->ThemeParameter(Padding, Px(15))      ->Children([        Text::Create()        ->ThemeParameter(PaddingBottom, Px(15))        ->Text("Pressed 0 times"),        Button::Create()        ->ThemeParameter(Width, Auto)        ->ThemeParameter(Padding, [Px(4), Px(10)])        ->ThemeParameter(BackgroundColor, Blue)        ->ThemeParameter(Color, White)        ->ThemeParameter(BorderRadius, Px(4))        ->Text("Press")      ])    );   }} ClickerDisplay::Display();

Выглядит куда лучше в несколько простых строчек.

Теперь можно добавить логику.

Для начала нужно инициализировать функцию Initialize() и создать приватную переменную TapCount.

Аналог form в фреймворке это Action.

Добавим Action в наше дерево элементов. Action тип пусть будет Post. В качестве детей укажем нашу колонку где находится наша кнопка.

Далее добавим click_count переменную в Action. А в качестве ее значение присвоим TapCount.

В Initialize() через Action::GetValue(name, standart_value, action_type) получим наше переменную. В качестве значения по умолчанию укажем 0, а в качестве типа укажем Post.

Добавим инкремент для нашей переменной.

В тексте выведим "Press $this->TapCount times".

Все, простой клинкер готов.

class ClickerDisplay extends DisplayComponent{  private $TapCount;  function Initialize() {    $this->TapCount = Action::GetValue("click_count", 0 /* standart value */, ActionTypes::Post);    $this->TapCount++;  }  function Build() : Document {    return Document::Create()    ->Title("Test page")    ->Child(      Action::Create()      ->Type(ActionTypes::Post)      ->Variable("click_count", $this->TapCount)      ->Child(        Column::Create()        ->ThemeParameter(Padding, Px(15))        ->Children([          Text::Create()          ->ThemeParameter(PaddingBottom, Px(15))          ->Text("Press $this->TapCount times"),          Button::Create()          ->ThemeParameter(Width, Auto)          ->ThemeParameter(Padding, [Px(4), Px(10)])          ->ThemeParameter(BackgroundColor, Blue)          ->ThemeParameter(Color, White)          ->ThemeParameter(BorderRadius, Px(4))          ->Text("Press")        ])      )    );  }} ClickerDisplay::Display();

Итог

Мне удалось написать простой, но достаточно мощный кодогенератор.

Он прошол путь от генерации простых таблиц до полноценного генератора html и css, на котором можно удобно верстать проекты и совмещять верстку с логикой.

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

Источники

GitHub MelonPHP

Flutter

MAUI