From 315c33b30c636a0a01c0d8f2e3bf0e49ebb84d40 Mon Sep 17 00:00:00 2001 From: oleibman <10341515+oleibman@users.noreply.github.com> Date: Sat, 9 Dec 2023 22:21:43 -0800 Subject: [PATCH] Automate Function-by-Name and Function-by-Category Docs Examining whether it is possible to analyze the 2 Php scripts in the bin directory even though they lack a .php extension, I found that the docs generated by `generate-document` had not been updated in over a year even though support for a number of functions (e.g. ARRAYTOTEXT) had long ago been implemented. The files generated by the other script `generate-locales` are automatically generated as part of the unit test suite, and I can't see any reason not to do the same for `generate-document`. It isn't totally clear that the 2 scripts in bin are needed any more now that each has an equivalent in the unit test suite. For now, I'm keeping them, and allowing them to be analyzed by phpcs, php-cs-fixer, and phpstan. --- .php-cs-fixer.dist.php | 1 + .phpcs.xml.dist | 2 ++ bin/generate-document | 6 ++-- bin/generate-locales | 2 +- docs/references/function-list-by-category.md | 26 +++++++++++++--- docs/references/function-list-by-name.md | 21 ++++++++++--- phpstan.neon.dist | 2 ++ .../DocumentGeneratorTest.php | 31 +++++++++++++++++++ 8 files changed, 78 insertions(+), 13 deletions(-) diff --git a/.php-cs-fixer.dist.php b/.php-cs-fixer.dist.php index 0eeaaa3b67..fb50aeaf51 100644 --- a/.php-cs-fixer.dist.php +++ b/.php-cs-fixer.dist.php @@ -3,6 +3,7 @@ $finder = PhpCsFixer\Finder::create() ->exclude('vendor') ->notPath('src/PhpSpreadsheet/Writer/ZipStream3.php') + ->name('/(\.php|^generate-document|^generate-locales)$/') ->in(__DIR__); $config = new PhpCsFixer\Config(); diff --git a/.phpcs.xml.dist b/.phpcs.xml.dist index ba381a28f7..d902156dc8 100644 --- a/.phpcs.xml.dist +++ b/.phpcs.xml.dist @@ -6,6 +6,8 @@ src tests infra + bin/generate-document + bin/generate-locales samples/Header.php */tests/Core/*/*Test\.(inc|css|js)$ diff --git a/bin/generate-document b/bin/generate-document index a8f334c9cb..f522244ab5 100755 --- a/bin/generate-document +++ b/bin/generate-document @@ -13,10 +13,12 @@ try { $phpSpreadsheetFunctions = $phpSpreadsheetFunctionsProperty->getValue(); ksort($phpSpreadsheetFunctions); - file_put_contents(__DIR__ . '/../docs/references/function-list-by-category.md', + file_put_contents( + __DIR__ . '/../docs/references/function-list-by-category.md', DocumentGenerator::generateFunctionListByCategory($phpSpreadsheetFunctions) ); - file_put_contents(__DIR__ . '/../docs/references/function-list-by-name.md', + file_put_contents( + __DIR__ . '/../docs/references/function-list-by-name.md', DocumentGenerator::generateFunctionListByName($phpSpreadsheetFunctions) ); } catch (ReflectionException $e) { diff --git a/bin/generate-locales b/bin/generate-locales index 30b9c55657..6ca0e3f7ae 100644 --- a/bin/generate-locales +++ b/bin/generate-locales @@ -13,7 +13,7 @@ try { $phpSpreadsheetFunctions = $phpSpreadsheetFunctionsProperty->getValue(); $localeGenerator = new LocaleGenerator( - realpath(__DIR__ . '/../src/PhpSpreadsheet/Calculation/locale/'), + (string) realpath(__DIR__ . '/../src/PhpSpreadsheet/Calculation/locale/'), 'Translations.xlsx', $phpSpreadsheetFunctions, true diff --git a/docs/references/function-list-by-category.md b/docs/references/function-list-by-category.md index d88d87dffd..353458ca40 100644 --- a/docs/references/function-list-by-category.md +++ b/docs/references/function-list-by-category.md @@ -200,6 +200,7 @@ ISNA | \PhpOffice\PhpSpreadsheet\Calculation\Information\Err ISNONTEXT | \PhpOffice\PhpSpreadsheet\Calculation\Information\Value::isNonText ISNUMBER | \PhpOffice\PhpSpreadsheet\Calculation\Information\Value::isNumber ISODD | \PhpOffice\PhpSpreadsheet\Calculation\Information\Value::isOdd +ISOMITTED | **Not yet Implemented** ISREF | \PhpOffice\PhpSpreadsheet\Calculation\Information\Value::isRef ISTEXT | \PhpOffice\PhpSpreadsheet\Calculation\Information\Value::isText N | \PhpOffice\PhpSpreadsheet\Calculation\Information\Value::asNumber @@ -213,13 +214,21 @@ TYPE | \PhpOffice\PhpSpreadsheet\Calculation\Information\Val Excel Function | PhpSpreadsheet Function -------------------------|-------------------------------------- AND | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Operations::logicalAnd +BYCOL | **Not yet Implemented** +BYROW | **Not yet Implemented** FALSE | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Boolean::FALSE IF | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Conditional::statementIf IFERROR | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Conditional::IFERROR IFNA | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Conditional::IFNA IFS | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Conditional::IFS +LAMBDA | **Not yet Implemented** +LET | **Not yet Implemented** +MAKEARRAY | **Not yet Implemented** +MAP | **Not yet Implemented** NOT | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Operations::NOT OR | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Operations::logicalOr +REDUCE | **Not yet Implemented** +SCAN | **Not yet Implemented** SWITCH | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Conditional::statementSwitch TRUE | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Boolean::TRUE XOR | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Operations::logicalXor @@ -513,7 +522,7 @@ ZTEST | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Dis Excel Function | PhpSpreadsheet Function -------------------------|-------------------------------------- -ARRAYTOTEXT | **Not yet Implemented** +ARRAYTOTEXT | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Text::fromArray ASC | **Not yet Implemented** BAHTTEXT | **Not yet Implemented** CHAR | \PhpOffice\PhpSpreadsheet\Calculation\TextData\CharacterConvert::character @@ -550,10 +559,10 @@ SEARCHB | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Search SUBSTITUTE | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Replace::substitute T | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Text::test TEXT | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Format::TEXTFORMAT -TEXTAFTER | **Not yet Implemented** -TEXTBEFORE | **Not yet Implemented** +TEXTAFTER | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Extract::after +TEXTBEFORE | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Extract::before TEXTJOIN | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Concatenate::TEXTJOIN -TEXTSPLIT | **Not yet Implemented** +TEXTSPLIT | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Text::split THAIDIGIT | **Not yet Implemented** THAINUMSOUND | **Not yet Implemented** THAINUMSTRING | **Not yet Implemented** @@ -563,7 +572,7 @@ UNICHAR | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Charac UNICODE | \PhpOffice\PhpSpreadsheet\Calculation\TextData\CharacterConvert::code UPPER | \PhpOffice\PhpSpreadsheet\Calculation\TextData\CaseConvert::upper VALUE | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Format::VALUE -VALUETOTEXT | **Not yet Implemented** +VALUETOTEXT | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Format::valueToText ## CATEGORY_WEB @@ -572,3 +581,10 @@ Excel Function | PhpSpreadsheet Function ENCODEURL | \PhpOffice\PhpSpreadsheet\Calculation\Web\Service::urlEncode FILTERXML | **Not yet Implemented** WEBSERVICE | \PhpOffice\PhpSpreadsheet\Calculation\Web\Service::webService + +## CATEGORY_UNCATEGORISED + +Excel Function | PhpSpreadsheet Function +-------------------------|-------------------------------------- +ANCHORARRAY | **Not yet Implemented** +SINGLE | **Not yet Implemented** diff --git a/docs/references/function-list-by-name.md b/docs/references/function-list-by-name.md index 7f91133b93..24c7f823ef 100644 --- a/docs/references/function-list-by-name.md +++ b/docs/references/function-list-by-name.md @@ -15,10 +15,11 @@ ADDRESS | CATEGORY_LOOKUP_AND_REFERENCE | \PhpOffice\PhpSpread AGGREGATE | CATEGORY_MATH_AND_TRIG | **Not yet Implemented** AMORDEGRC | CATEGORY_FINANCIAL | \PhpOffice\PhpSpreadsheet\Calculation\Financial\Amortization::AMORDEGRC AMORLINC | CATEGORY_FINANCIAL | \PhpOffice\PhpSpreadsheet\Calculation\Financial\Amortization::AMORLINC +ANCHORARRAY | CATEGORY_UNCATEGORISED | **Not yet Implemented** AND | CATEGORY_LOGICAL | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Operations::logicalAnd ARABIC | CATEGORY_MATH_AND_TRIG | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Arabic::evaluate AREAS | CATEGORY_LOOKUP_AND_REFERENCE | **Not yet Implemented** -ARRAYTOTEXT | CATEGORY_TEXT_AND_DATA | **Not yet Implemented** +ARRAYTOTEXT | CATEGORY_TEXT_AND_DATA | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Text::fromArray ASC | CATEGORY_TEXT_AND_DATA | **Not yet Implemented** ASIN | CATEGORY_MATH_AND_TRIG | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Trig\Sine::asin ASINH | CATEGORY_MATH_AND_TRIG | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Trig\Sine::asinh @@ -57,6 +58,8 @@ BITLSHIFT | CATEGORY_ENGINEERING | \PhpOffice\PhpSpread BITOR | CATEGORY_ENGINEERING | \PhpOffice\PhpSpreadsheet\Calculation\Engineering\BitWise::BITOR BITRSHIFT | CATEGORY_ENGINEERING | \PhpOffice\PhpSpreadsheet\Calculation\Engineering\BitWise::BITRSHIFT BITXOR | CATEGORY_ENGINEERING | \PhpOffice\PhpSpreadsheet\Calculation\Engineering\BitWise::BITXOR +BYCOL | CATEGORY_LOGICAL | **Not yet Implemented** +BYROW | CATEGORY_LOGICAL | **Not yet Implemented** ## C @@ -305,6 +308,7 @@ ISNONTEXT | CATEGORY_INFORMATION | \PhpOffice\PhpSpread ISNUMBER | CATEGORY_INFORMATION | \PhpOffice\PhpSpreadsheet\Calculation\Information\Value::isNumber ISO.CEILING | CATEGORY_MATH_AND_TRIG | **Not yet Implemented** ISODD | CATEGORY_INFORMATION | \PhpOffice\PhpSpreadsheet\Calculation\Information\Value::isOdd +ISOMITTED | CATEGORY_INFORMATION | **Not yet Implemented** ISOWEEKNUM | CATEGORY_DATE_AND_TIME | \PhpOffice\PhpSpreadsheet\Calculation\DateTimeExcel\Week::isoWeekNumber ISPMT | CATEGORY_FINANCIAL | \PhpOffice\PhpSpreadsheet\Calculation\Financial\CashFlow\Constant\Periodic\Interest::schedulePayment ISREF | CATEGORY_INFORMATION | \PhpOffice\PhpSpreadsheet\Calculation\Information\Value::isRef @@ -327,12 +331,14 @@ KURT | CATEGORY_STATISTICAL | \PhpOffice\PhpSpread Excel Function | Category | PhpSpreadsheet Function -------------------------|--------------------------------|-------------------------------------- +LAMBDA | CATEGORY_LOGICAL | **Not yet Implemented** LARGE | CATEGORY_STATISTICAL | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Size::large LCM | CATEGORY_MATH_AND_TRIG | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Lcm::evaluate LEFT | CATEGORY_TEXT_AND_DATA | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Extract::left LEFTB | CATEGORY_TEXT_AND_DATA | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Extract::left LEN | CATEGORY_TEXT_AND_DATA | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Text::length LENB | CATEGORY_TEXT_AND_DATA | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Text::length +LET | CATEGORY_LOGICAL | **Not yet Implemented** LINEST | CATEGORY_STATISTICAL | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Trends::LINEST LN | CATEGORY_MATH_AND_TRIG | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Logarithms::natural LOG | CATEGORY_MATH_AND_TRIG | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Logarithms::withBase @@ -349,6 +355,8 @@ LOWER | CATEGORY_TEXT_AND_DATA | \PhpOffice\PhpSpread Excel Function | Category | PhpSpreadsheet Function -------------------------|--------------------------------|-------------------------------------- +MAKEARRAY | CATEGORY_LOGICAL | **Not yet Implemented** +MAP | CATEGORY_LOGICAL | **Not yet Implemented** MATCH | CATEGORY_LOOKUP_AND_REFERENCE | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\ExcelMatch::MATCH MAX | CATEGORY_STATISTICAL | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Maximum::max MAXA | CATEGORY_STATISTICAL | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Maximum::maxA @@ -468,6 +476,7 @@ RANK.AVG | CATEGORY_STATISTICAL | **Not yet Implemente RANK.EQ | CATEGORY_STATISTICAL | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Percentiles::RANK RATE | CATEGORY_FINANCIAL | \PhpOffice\PhpSpreadsheet\Calculation\Financial\CashFlow\Constant\Periodic\Interest::rate RECEIVED | CATEGORY_FINANCIAL | \PhpOffice\PhpSpreadsheet\Calculation\Financial\Securities\Price::received +REDUCE | CATEGORY_LOGICAL | **Not yet Implemented** REPLACE | CATEGORY_TEXT_AND_DATA | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Replace::replace REPLACEB | CATEGORY_TEXT_AND_DATA | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Replace::replace REPT | CATEGORY_TEXT_AND_DATA | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Concatenate::builtinREPT @@ -489,6 +498,7 @@ RTD | CATEGORY_LOOKUP_AND_REFERENCE | **Not yet Implemente Excel Function | Category | PhpSpreadsheet Function -------------------------|--------------------------------|-------------------------------------- +SCAN | CATEGORY_LOGICAL | **Not yet Implemented** SEARCH | CATEGORY_TEXT_AND_DATA | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Search::insensitive SEARCHB | CATEGORY_TEXT_AND_DATA | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Search::insensitive SEC | CATEGORY_MATH_AND_TRIG | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Trig\Secant::sec @@ -500,6 +510,7 @@ SHEET | CATEGORY_INFORMATION | **Not yet Implemente SHEETS | CATEGORY_INFORMATION | **Not yet Implemented** SIGN | CATEGORY_MATH_AND_TRIG | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Sign::evaluate SIN | CATEGORY_MATH_AND_TRIG | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Trig\Sine::sin +SINGLE | CATEGORY_UNCATEGORISED | **Not yet Implemented** SINH | CATEGORY_MATH_AND_TRIG | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Trig\Sine::sinh SKEW | CATEGORY_STATISTICAL | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Deviations::skew SKEW.P | CATEGORY_STATISTICAL | **Not yet Implemented** @@ -550,10 +561,10 @@ TBILLPRICE | CATEGORY_FINANCIAL | \PhpOffice\PhpSpread TBILLYIELD | CATEGORY_FINANCIAL | \PhpOffice\PhpSpreadsheet\Calculation\Financial\TreasuryBill::yield TDIST | CATEGORY_STATISTICAL | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Distributions\StudentT::distribution TEXT | CATEGORY_TEXT_AND_DATA | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Format::TEXTFORMAT -TEXTAFTER | CATEGORY_TEXT_AND_DATA | **Not yet Implemented** -TEXTBEFORE | CATEGORY_TEXT_AND_DATA | **Not yet Implemented** +TEXTAFTER | CATEGORY_TEXT_AND_DATA | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Extract::after +TEXTBEFORE | CATEGORY_TEXT_AND_DATA | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Extract::before TEXTJOIN | CATEGORY_TEXT_AND_DATA | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Concatenate::TEXTJOIN -TEXTSPLIT | CATEGORY_TEXT_AND_DATA | **Not yet Implemented** +TEXTSPLIT | CATEGORY_TEXT_AND_DATA | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Text::split THAIDAYOFWEEK | CATEGORY_DATE_AND_TIME | **Not yet Implemented** THAIDIGIT | CATEGORY_TEXT_AND_DATA | **Not yet Implemented** THAIMONTHOFYEAR | CATEGORY_DATE_AND_TIME | **Not yet Implemented** @@ -591,7 +602,7 @@ USDOLLAR | CATEGORY_FINANCIAL | \PhpOffice\PhpSpread Excel Function | Category | PhpSpreadsheet Function -------------------------|--------------------------------|-------------------------------------- VALUE | CATEGORY_TEXT_AND_DATA | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Format::VALUE -VALUETOTEXT | CATEGORY_TEXT_AND_DATA | **Not yet Implemented** +VALUETOTEXT | CATEGORY_TEXT_AND_DATA | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Format::valueToText VAR | CATEGORY_STATISTICAL | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Variances::VAR VAR.P | CATEGORY_STATISTICAL | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Variances::VARP VAR.S | CATEGORY_STATISTICAL | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Variances::VAR diff --git a/phpstan.neon.dist b/phpstan.neon.dist index 154541708c..de87870ec7 100644 --- a/phpstan.neon.dist +++ b/phpstan.neon.dist @@ -10,6 +10,8 @@ parameters: - tests/ - samples/ - infra/ + - bin/generate-document + - bin/generate-locales excludePaths: - src/PhpSpreadsheet/Chart/Renderer/JpGraph.php - src/PhpSpreadsheet/Chart/Renderer/JpGraphRendererBase.php diff --git a/tests/PhpSpreadsheetTests/DocumentGeneratorTest.php b/tests/PhpSpreadsheetTests/DocumentGeneratorTest.php index ef1d3d3529..b5b07c4ffb 100644 --- a/tests/PhpSpreadsheetTests/DocumentGeneratorTest.php +++ b/tests/PhpSpreadsheetTests/DocumentGeneratorTest.php @@ -4,21 +4,28 @@ namespace PhpOffice\PhpSpreadsheetTests; +use PhpOffice\PhpSpreadsheet\Calculation\Calculation; use PhpOffice\PhpSpreadsheet\Calculation\Category as Cat; use PhpOffice\PhpSpreadsheet\Calculation\Functions; use PhpOffice\PhpSpreadsheet\Calculation\Logical; use PhpOffice\PhpSpreadsheetInfra\DocumentGenerator; use PHPUnit\Framework\TestCase; +use ReflectionClass; use UnexpectedValueException; class DocumentGeneratorTest extends TestCase { + private static bool $succeededByName = false; + + private static bool $succeededByCategory = false; + /** * @dataProvider providerGenerateFunctionListByName */ public function testGenerateFunctionListByName(array $phpSpreadsheetFunctions, string $expected): void { self::assertEquals($expected, DocumentGenerator::generateFunctionListByName($phpSpreadsheetFunctions)); + self::$succeededByName = true; } /** @@ -27,6 +34,7 @@ public function testGenerateFunctionListByName(array $phpSpreadsheetFunctions, s public function testGenerateFunctionListByCategory(array $phpSpreadsheetFunctions, string $expected): void { self::assertEquals($expected, DocumentGenerator::generateFunctionListByCategory($phpSpreadsheetFunctions)); + self::$succeededByCategory = true; } public static function providerGenerateFunctionListByName(): array @@ -154,4 +162,27 @@ public function testGenerateFunctionBadArray(): void ]; DocumentGenerator::generateFunctionListByName($phpSpreadsheetFunctions); } + + public function testGenerateDocuments(): void + { + if (!self::$succeededByName || !self::$succeededByCategory) { + self::markTestSkipped('Not run because prior test failed'); + } + $directory = 'docs/references/'; + self::assertNotEmpty($directory); + $phpSpreadsheetFunctionsProperty = (new ReflectionClass(Calculation::class)) + ->getProperty('phpSpreadsheetFunctions'); + $phpSpreadsheetFunctionsProperty->setAccessible(true); + $phpSpreadsheetFunctions = $phpSpreadsheetFunctionsProperty->getValue(); + ksort($phpSpreadsheetFunctions); + + self::assertNotFalse(file_put_contents( + $directory . 'function-list-by-category.md', + DocumentGenerator::generateFunctionListByCategory($phpSpreadsheetFunctions) + )); + self::assertNotFalse(file_put_contents( + $directory . 'function-list-by-name.md', + DocumentGenerator::generateFunctionListByName($phpSpreadsheetFunctions) + )); + } }