Replaced higlightjs with prism with links to dsl functions docs

bin/docs.php

@@ -46,6 +46,9 @@ public function execute(InputInterface $input, OutputInterface $output) : int
             __DIR__ . '/../src/adapter/etl-adapter-parquet/src/Flow/ETL/Adapter/Parquet/functions.php',
             __DIR__ . '/../src/adapter/etl-adapter-text/src/Flow/ETL/Adapter/Text/functions.php',
             __DIR__ . '/../src/adapter/etl-adapter-xml/src/Flow/ETL/Adapter/XML/functions.php',
+            __DIR__ . '/../src/lib/filesystem/src/Flow/Filesystem/DSL/functions.php',
+            __DIR__ . '/../src/bridge/filesystem/azure/src/Flow/Filesystem/Bridge/Azure/DSL/functions.php',
+            __DIR__ . '/../src/lib/azure-sdk/src/Flow/Azure/SDK/DSL/functions.php',
         ];
 
         $extractor = new FunctionsExtractor(

phpunit.xml.dist

@@ -42,6 +42,7 @@
       <directory>src/bridge/**/**/**/**/**/**/Tests/Integration</directory>
       <directory>src/core/etl/tests/Flow/ETL/Tests/Integration</directory>
       <directory>src/lib/**/**/**/**/Tests/Integration</directory>
+      <directory>src/tools/**/**/**/**/Tests/Integration</directory>
       <directory>src/lib/doctrine-dbal-bulk/tests/Flow/Doctrine/Bulk/Tests/Integration</directory>
     </testsuite>
   </testsuites>
@@ -51,6 +52,7 @@
       <directory suffix=".php">src/bridge/**/src</directory>
       <directory suffix=".php">src/core/**/src</directory>
       <directory suffix=".php">src/lib/**/src</directory>
+      <directory suffix=".php">src/tools/**/src</directory>
     </include>
     <exclude>
       <directory suffix=".php">src/lib/parquet/src/Flow/Parquet/Thrift</directory>

src/adapter/etl-adapter-chartjs/src/Flow/ETL/Adapter/ChartJS/functions.php

@@ -5,24 +5,29 @@
 namespace Flow\ETL\Adapter\ChartJS;
 
 use Flow\ETL\Adapter\ChartJS\Chart\{BarChart, LineChart, PieChart};
+use Flow\ETL\Attribute\{DSL, Module, Type};
 use Flow\ETL\Row\{EntryReference, References};
 use Flow\Filesystem\Path;
 
+#[DSL(module: Module::CHARTJS, type: Type::HELPER)]
 function bar_chart(EntryReference $label, References $datasets) : BarChart
 {
     return new BarChart($label, $datasets);
 }
 
+#[DSL(module: Module::CHARTJS, type: Type::HELPER)]
 function line_chart(EntryReference $label, References $datasets) : LineChart
 {
     return new LineChart($label, $datasets);
 }
 
+#[DSL(module: Module::CHARTJS, type: Type::HELPER)]
 function pie_chart(EntryReference $label, References $datasets) : PieChart
 {
     return new PieChart($label, $datasets);
 }
 
+#[DSL(module: Module::CHARTJS, type: Type::LOADER)]
 function to_chartjs_file(Chart $type, Path|string|null $output = null, Path|string|null $template = null) : ChartJSLoader
 {
     if (\is_string($output)) {
@@ -40,6 +45,7 @@ function to_chartjs_file(Chart $type, Path|string|null $output = null, Path|stri
     return new ChartJSLoader($type, output: $output, template: $template);
 }
 
+#[DSL(module: Module::CHARTJS, type: Type::LOADER)]
 function to_chartjs_var(Chart $type, array &$output) : ChartJSLoader
 {
     /** @psalm-suppress ReferenceConstraintViolation */

src/adapter/etl-adapter-xml/src/Flow/ETL/Adapter/XML/functions.php

@@ -8,12 +8,16 @@
 use Flow\ETL\{Adapter\XML\Loader\XMLLoader,
     Adapter\XML\RowsNormalizer\EntryNormalizer\PHPValueNormalizer,
     Adapter\XML\XMLWriter\DOMDocumentWriter,
+    Attribute\DSL,
+    Attribute\Module,
+    Attribute\Type as DSLType,
     Extractor};
 use Flow\Filesystem\Path;
 
 /**
  * @param array<Path|string>|Path|string $path
  */
+#[DSL(module: Module::XML, type: DSLType::EXTRACTOR)]
 function from_xml(
     string|Path|array $path,
     string $xml_node_path = ''
@@ -38,6 +42,7 @@ function from_xml(
     );
 }
 
+#[DSL(module: Module::XML, type: DSLType::LOADER)]
 function to_xml(
     string|Path $path,
     string $root_element_name = 'rows',

src/bridge/filesystem/azure/src/Flow/Filesystem/Bridge/Azure/DSL/functions.php

@@ -5,13 +5,16 @@
 namespace Flow\Filesystem\Bridge\Azure\DSL;
 
 use Flow\Azure\SDK\BlobServiceInterface;
+use Flow\ETL\Attribute\{DSL, Module, Type};
 use Flow\Filesystem\Bridge\Azure\{AzureBlobFilesystem, Options};
 
+#[DSL(module: Module::AZURE_FILESYSTEM, type: Type::HELPER)]
 function azure_filesystem_options() : Options
 {
     return new Options();
 }
 
+#[DSL(module: Module::AZURE_FILESYSTEM, type: Type::HELPER)]
 function azure_filesystem(BlobServiceInterface $blob_service, Options $options = new Options()) : AzureBlobFilesystem
 {
     return new AzureBlobFilesystem($blob_service, $options);

src/core/etl/src/Flow/ETL/Attribute/Module.php

@@ -6,11 +6,14 @@
 
 enum Module : string
 {
+    case AZURE_FILESYSTEM = 'Azure Filesystem';
+    case AZURE_SDK = 'Azure SDK';
     case CHARTJS = 'ChartJS';
     case CORE = 'Core';
     case CSV = 'CSV';
     case DOCTRINE = 'Doctrine';
     case ELASTICSEARCH = 'Elastic Search';
+    case FILESYSTEM = 'Filesystem';
     case GOOGLE_SHEET = 'Google Sheet';
     case JSON = 'JSON';
     case MEILI_SEARCH = 'MeiliSearch';

src/lib/azure-sdk/src/Flow/Azure/SDK/DSL/functions.php

@@ -8,36 +8,43 @@
 use Flow\Azure\SDK\BlobService\Configuration;
 use Flow\Azure\SDK\BlobService\URLFactory\{AzureURLFactory, AzuriteURLFactory};
 use Flow\Azure\SDK\{AuthorizationFactory, BlobService, BlobServiceInterface, HttpFactory, URLFactory};
+use Flow\ETL\Attribute\{DSL, Module, Type};
 use Http\Discovery\{Psr17FactoryDiscovery, Psr18ClientDiscovery};
 use Psr\Http\Client\ClientInterface;
 use Psr\Http\Message\{RequestFactoryInterface, StreamFactoryInterface};
 use Psr\Log\{LoggerInterface, NullLogger};
 
+#[DSL(module: Module::AZURE_SDK, type: Type::HELPER)]
 function azurite_url_factory(string $host = 'localhost', string $port = '10000', bool $secure = false) : AzuriteURLFactory
 {
     return new AzuriteURLFactory($host, $port, $secure);
 }
 
+#[DSL(module: Module::AZURE_SDK, type: Type::HELPER)]
 function azure_shared_key_authorization_factory(#[\SensitiveParameter] string $account, #[\SensitiveParameter] string $key) : SharedKeyFactory
 {
     return new SharedKeyFactory($account, $key);
 }
 
+#[DSL(module: Module::AZURE_SDK, type: Type::HELPER)]
 function azure_blob_service_config(string $account, string $container) : Configuration
 {
     return new Configuration($account, $container);
 }
 
+#[DSL(module: Module::AZURE_SDK, type: Type::HELPER)]
 function azure_url_factory(string $host = 'blob.core.windows.net') : AzureURLFactory
 {
     return new AzureURLFactory($host);
 }
 
+#[DSL(module: Module::AZURE_SDK, type: Type::HELPER)]
 function azure_http_factory(RequestFactoryInterface $request_factory, StreamFactoryInterface $stream_factory) : HttpFactory
 {
     return new HttpFactory($request_factory, $stream_factory);
 }
 
+#[DSL(module: Module::AZURE_SDK, type: Type::HELPER)]
 function azure_blob_service(
     Configuration $configuration,
     AuthorizationFactory $azure_authorization_factory,

src/lib/filesystem/src/Flow/Filesystem/DSL/functions.php

@@ -4,42 +4,70 @@
 
 namespace Flow\Filesystem\DSL;
 
+use Flow\ETL\Attribute\{DSL, Module, Type};
 use Flow\Filesystem\Local\NativeLocalFilesystem;
 use Flow\Filesystem\{Filesystem, FilesystemTable, Partition, Partitions, Path, Protocol};
 
+#[DSL(module: Module::FILESYSTEM, type: Type::HELPER)]
 function protocol(string $protocol) : Protocol
 {
     return new Protocol($protocol);
 }
 
+#[DSL(module: Module::FILESYSTEM, type: Type::HELPER)]
 function partition(string $name, string $value) : Partition
 {
     return new Partition($name, $value);
 }
 
+#[DSL(module: Module::FILESYSTEM, type: Type::HELPER)]
 function partitions(Partition ...$partition) : Partitions
 {
     return new Partitions(...$partition);
 }
 
 /**
+ * Path supports glob patterns.
+ * Examples:
+ *  - path('*.csv') - any csv file in current directory
+ *  - path('/** / *.csv') - any csv file in any subdirectory (remove empty spaces)
+ *  - path('/dir/partition=* /*.parquet') - any parquet file in given partition directory.
+ *
+ * Glob pattern is also supported by remote filesystems like Azure
+ *
+ *  - path('azure-blob://directory/*.csv') - any csv file in given directory
+ *
  * @param array<string, mixed> $options
  */
+#[DSL(module: Module::FILESYSTEM, type: Type::HELPER)]
 function path(string $path, array $options = []) : Path
 {
     return new Path($path, $options);
 }
 
+/**
+ * Resolve real path from given path.
+ *
+ * @param array<string, mixed> $options
+ */
+#[DSL(module: Module::FILESYSTEM, type: Type::HELPER)]
 function path_real(string $path, array $options = []) : Path
 {
     return Path::realpath($path, $options);
 }
 
+#[DSL(module: Module::FILESYSTEM, type: Type::HELPER)]
 function native_local_filesystem() : NativeLocalFilesystem
 {
     return new NativeLocalFilesystem();
 }
 
+/**
+ * Create a new filesystem table with given filesystems.
+ * Filesystems can be also mounted later.
+ * If no filesystems are provided, local filesystem is mounted.
+ */
+#[DSL(module: Module::FILESYSTEM, type: Type::HELPER)]
 function fstab(Filesystem ...$filesystems) : FilesystemTable
 {
     if (!\count($filesystems)) {

src/tools/documentation/tests/Flow/Documentation/Tests/Integration/FunctionsExtractorTest.php

@@ -12,6 +12,7 @@ final class FunctionsExtractorTest extends TestCase
     public function test_extract_functions_from_a_file() : void
     {
         $functionsExtractor = new FunctionsExtractor(
+            __DIR__,
             new FunctionCollector()
         );
 
@@ -81,6 +82,8 @@ public function test_extract_functions_from_a_file() : void
                     ],
                 ],
                 'doc_comment' => null,
+                'repository_path' => 'functions.php',
+                'start_line_in_file' => 10,
             ],
             $functions[0]->normalize()
         );

web/landing/assets/controllers/syntax_highlight_controller.js

@@ -1,22 +1,17 @@
 import {Controller} from '@hotwired/stimulus';
-import 'highlight.js/styles/github-dark.min.css';
-import php from 'highlight.js/lib/languages/php';
-import shell from 'highlight.js/lib/languages/shell';
-import json from 'highlight.js/lib/languages/json';
-import hljs from 'highlight.js/lib/core';
+import Prism from 'prismjs';
+import '../prismjs/themes/prism-flow.css';
+import '../prismjs/plugins/autolinker/autolinker.js';
+import 'prismjs/plugins/autoloader/prism-autoloader.js';
+import 'prismjs/components/prism-markup-templating.min.js';
+import 'prismjs/components/prism-php.min.js';
+import 'prismjs/components/prism-bash.min.js';
 
 /* stimulusFetch: 'lazy' */
 export default class extends Controller
 {
     initialize()
     {
-        hljs.registerLanguage('php', php);
-        hljs.registerLanguage('shell', shell);
-        hljs.registerLanguage('json', json);
-    }
-
-    connect()
-    {
-        hljs.highlightElement(this.element);
+        Prism.highlightElement(this.element);
     }
 }

web/landing/assets/prismjs/plugins/autolinker/autolinker.js

@@ -0,0 +1,43 @@
+(function () {
+
+    if (typeof Prism === 'undefined') {
+        return;
+    }
+
+    const functions = window.flow.dsl.map(function (item) {
+        return {
+            name: item.name,
+            module: item.attributes.find(attribute => attribute.name === 'DSL')?.arguments.module.toLowerCase()
+        };
+    });
+
+    // URL template
+    const urlTemplate = "/documentation/dsl/{module_name}/{function_name}#dsl-function";
+
+    Prism.hooks.add('after-highlight', function(env) {
+
+        if (env.language !== 'php') return;
+
+        if (env.element.getAttribute('data-prismjs-no-auto-linker') !== null) {
+            return;
+        }
+
+        // Find all tokens of type 'function' and 'function-method'
+        const functionTokens = env.element.querySelectorAll('.token.function, .token.function-method');
+
+        functionTokens.forEach(function(token) {
+            const functionName = token.textContent;
+
+            let definition = functions.find(f => f.name === functionName);
+
+            if (definition) {
+                const link = document.createElement('a');
+                link.href = urlTemplate.replace('{module_name}', definition.module).replace('{function_name}', definition.name);
+                link.target = '_blank';
+                link.textContent = functionName;
+                link.className = token.className;
+                token.parentNode.replaceChild(link, token);
+            }
+        });
+    });
+}());