From 1b38b9c042a1d419bf4e221a67cbb6fe92079dcd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20Andr=C3=A9?= Date: Sat, 19 Sep 2026 23:14:22 +0200 Subject: [PATCH] docs: update structure --- README.md | 14 +++-- docs/catalog.md | 128 ++++++++++++++++++++-------------------- docs/definitions.md | 17 ++++++ docs/getting-started.md | 23 ++++++-- docs/index.md | 28 ++++----- docs/lookup.md | 34 +++++++++++ 6 files changed, 155 insertions(+), 89 deletions(-) diff --git a/README.md b/README.md index a1aba7f..8b614d8 100644 --- a/README.md +++ b/README.md @@ -52,11 +52,15 @@ identifier may be a slug, alias, extension, or filename. ## Documentation -The [ALTO Language documentation](https://altophp.com/language/) covers: - -- [lookup rules](https://altophp.com/language/lookup/); -- the [bundled catalog](https://altophp.com/language/catalog/); -- [language definitions and custom registration](https://altophp.com/language/definitions/). +- [Installation](docs/installation.md) +- [Getting started](docs/getting-started.md) +- [Lookup](docs/lookup.md) +- [Catalog](docs/catalog.md) +- [Definitions](docs/definitions.md) + +The [documentation index](docs/index.md) lists these pages in site navigation +order. The same documentation is published on +[altophp.com](https://altophp.com/language). ## Contributing diff --git a/docs/catalog.md b/docs/catalog.md index be636a1..c71df6e 100644 --- a/docs/catalog.md +++ b/docs/catalog.md @@ -16,70 +16,70 @@ $javascriptFamily = Languages::children('javascript'); `all()` preserves definition loading order. `ofType()` and `children()` return filtered lists of `Language` objects. -| Language | Extensions | Type | -| --- | --- | --- | -| Bash | `.sh`, `.bash` | Programming | -| C | `.c`, `.h` | Programming | -| C# | `.cs` | Programming | -| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp` | Programming | -| Clojure | `.clj`, `.cljs`, `.cljc` | Programming | -| CMake | `.cmake` | Programming | -| CoffeeScript | `.coffee` | Programming | -| CSS | `.css` | Stylesheet | -| Dart | `.dart` | Programming | -| Diff | `.diff`, `.patch` | Data | -| Dockerfile | Exact filenames | Config | -| Dotenv | Exact filenames | Config | -| Elixir | `.ex`, `.exs` | Programming | -| Erlang | `.erl`, `.hrl` | Programming | -| F# | `.fs`, `.fsi`, `.fsx` | Programming | -| Git Attributes | Exact filenames | Config | -| Git Config | Exact filenames | Config | -| Go | `.go` | Programming | -| GraphQL | `.graphql`, `.gql` | Query | -| Groovy | `.groovy`, `.gvy` | Programming | -| Haskell | `.hs`, `.lhs` | Programming | -| HCL | `.hcl`, `.tf` | Programming | -| htaccess | Exact filenames | Config | -| HTML | `.html`, `.htm` | Markup | -| HTTP | `.http`, `.rest` | Data | -| Ignore | Exact filenames | Config | -| INI | `.ini`, `.cfg` | Config | -| Java | `.java` | Programming | -| JavaScript | `.js`, `.mjs`, `.cjs`, `.jsx` | Programming | -| JSON | `.json` | Data | -| Julia | `.jl` | Programming | -| Just | Exact filenames | Config | -| Kotlin | `.kt`, `.kts` | Programming | -| Less | `.less` | Stylesheet | -| Lua | `.lua` | Programming | -| Makefile | Exact filenames | Programming | -| Markdown | `.md`, `.markdown` | Prose | -| NEON | `.neon` | Config | -| Nix | `.nix` | Programming | -| Objective-C | `.m`, `.mm` | Programming | -| OCaml | `.ml`, `.mli` | Programming | -| Perl | `.pl`, `.pm` | Programming | -| PHP | `.php`, `.phtml`, `.php3`, `.php4`, `.php5`, `.phps` | Programming | -| PowerShell | `.ps1`, `.psm1` | Programming | -| Procfile | Exact filenames | Config | -| Protocol Buffers | `.proto` | Data | -| Python | `.py`, `.pyw` | Programming | -| R | `.r`, `.R` | Programming | -| Ruby | `.rb` | Programming | -| Rust | `.rs` | Programming | -| Sass | `.sass` | Stylesheet | -| Scala | `.scala`, `.sc` | Programming | -| SCSS | `.scss` | Stylesheet | -| SQL | `.sql` | Query | -| SVG | `.svg` | Markup | -| Swift | `.swift` | Programming | -| TOML | `.toml` | Config | -| Twig | `.twig` | Template | -| TypeScript | `.ts`, `.tsx`, `.mts`, `.cts` | Programming | -| XML | `.xml`, `.xsl`, `.xsd` | Markup | -| YAML | `.yml`, `.yaml` | Data | -| Zig | `.zig` | Programming | +| Language | Extensions | Exact filenames | Type | +| --- | --- | --- | --- | +| Bash | `.sh`, `.bash`, `.zsh` | `.bashrc`, `.bash_profile`, `.bash_logout`, `.profile` | Programming | +| C | `.c`, `.h` | - | Programming | +| Clojure | `.clj`, `.cljs`, `.cljc`, `.edn` | - | Programming | +| CMake | `.cmake` | `CMakeLists.txt` | Config | +| CoffeeScript | `.coffee`, `.litcoffee` | - | Programming | +| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hh`, `.hxx` | - | Programming | +| C# | `.cs`, `.csx` | - | Programming | +| CSS | `.css` | - | Stylesheet | +| Dart | `.dart` | - | Programming | +| Diff | `.diff`, `.patch` | - | Other | +| Dockerfile | `.dockerfile` | `Dockerfile`, `Dockerfile.dev`, `Dockerfile.prod` | Config | +| DotEnv | `.env` | `.env`, `.env.local`, `.env.production`, `.env.development` | Config | +| Elixir | `.ex`, `.exs` | - | Programming | +| Erlang | `.erl`, `.hrl` | - | Programming | +| F# | `.fs`, `.fsx`, `.fsi` | - | Programming | +| Git Attributes | - | `.gitattributes` | Config | +| Git Config | `.gitconfig` | `.gitconfig`, `.gitmodules`, `.mailmap` | Config | +| Go | `.go` | - | Programming | +| GraphQL | `.graphql`, `.gql` | - | Query | +| Groovy | `.groovy`, `.gvy`, `.gy`, `.gsh` | - | Programming | +| Haskell | `.hs`, `.lhs` | - | Programming | +| HCL | `.hcl`, `.tf`, `.tfvars` | - | Config | +| Apache Config | - | `.htaccess`, `.htpasswd` | Config | +| HTML | `.html`, `.htm`, `.xhtml` | - | Markup | +| HTTP | `.http` | - | Other | +| Ignore List | - | `.gitignore`, `.dockerignore`, `.npmignore`, `.eslintignore`, `.prettierignore`, `.stylelintignore`, `.hgignore`, `.nowignore`, `.vercelignore`, `.gcloudignore` | Config | +| INI | `.ini`, `.cfg`, `.properties` | `.editorconfig`, `.npmrc` | Config | +| Java | `.java` | - | Programming | +| JavaScript | `.js`, `.mjs`, `.cjs`, `.jsx` | - | Programming | +| JSON | `.json`, `.jsonc`, `.geojson`, `.json5` | `.prettierrc`, `.eslintrc`, `.babelrc`, `.swcrc`, `composer.lock` | Data | +| Julia | `.jl` | - | Programming | +| Just | - | `Justfile`, `justfile` | Config | +| Kotlin | `.kt`, `.kts` | - | Programming | +| Less | `.less` | - | Stylesheet | +| Lua | `.lua` | - | Programming | +| Makefile | `.mk` | `Makefile`, `GNUmakefile`, `makefile` | Config | +| Markdown | `.md`, `.markdown`, `.mdx` | - | Prose | +| NEON | `.neon` | - | Config | +| Nix | `.nix` | - | Config | +| Objective-C | `.m`, `.mm` | - | Programming | +| OCaml | `.ml`, `.mli` | - | Programming | +| Perl | `.pl`, `.pm`, `.t` | - | Programming | +| PHP | `.php`, `.phtml`, `.php3`, `.php4`, `.php5`, `.phps` | - | Programming | +| PowerShell | `.ps1`, `.psm1`, `.psd1` | - | Programming | +| Procfile | - | `Procfile` | Config | +| Protocol Buffers | `.proto` | - | Data | +| Python | `.py`, `.pyi`, `.pyw` | - | Programming | +| R | `.r`, `.R`, `.rmd` | - | Programming | +| Ruby | `.rb`, `.rake`, `.gemspec` | `Gemfile`, `Rakefile`, `Guardfile`, `Vagrantfile`, `Podfile`, `Capfile`, `Brewfile`, `Berksfile` | Programming | +| Rust | `.rs` | - | Programming | +| Sass | `.sass` | - | Stylesheet | +| Scala | `.scala`, `.sc` | - | Programming | +| SCSS | `.scss` | - | Stylesheet | +| SQL | `.sql` | - | Query | +| SVG | `.svg` | - | Markup | +| Swift | `.swift` | - | Programming | +| TOML | `.toml` | - | Data | +| Twig | `.twig`, `.html.twig` | - | Template | +| TypeScript | `.ts`, `.tsx`, `.mts`, `.cts` | - | Programming | +| XML | `.xml`, `.xsd`, `.xsl`, `.xslt`, `.wsdl` | - | Markup | +| YAML | `.yml`, `.yaml` | - | Data | +| Zig | `.zig` | - | Programming | Types are represented by `LanguageType`: `Programming`, `Markup`, `Data`, `Prose`, `Query`, `Stylesheet`, `Template`, `Config`, and `Other`. diff --git a/docs/definitions.md b/docs/definitions.md index e10f3c1..5983dc5 100644 --- a/docs/definitions.md +++ b/docs/definitions.md @@ -39,6 +39,10 @@ describe common conventions; they are not a parser grammar. ## Register an application language ```php +register(new Language( )); $language = $registry->fromExtension('.myl'); +printf("%s (%s)\n", $language?->name, $language?->slug); +echo json_encode($language?->markers->lineComments, JSON_THROW_ON_ERROR), "\n"; +``` + +Output: + +```text +My Language (my-language) +["\/\/"] ``` Bundled definitions are loaded lazily. A custom registration with the same @@ -63,3 +76,7 @@ extension, alias, or filename. Inspect collisions with `$registry->conflicts()`. The result groups repeated keys under `extension`, `alias`, and `filename`. + +Keep application registries separate when one service should not see another +service's custom definitions. Check `conflicts()` before choosing an ambiguous +alias or extension. Registration changes lookup metadata, not a syntax parser. diff --git a/docs/getting-started.md b/docs/getting-started.md index b18c1ec..2f07121 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -3,23 +3,38 @@ Use `Languages::fromFilename()` when an application has a path and wants the best matching bundled definition. +After [installation](installation.md), save this as `language.php` beside `vendor` +and run `php language.php`. An unknown identifier is a normal `null` result. + ```php +name, $language->type->value); +echo Languages::resolve('not-a-language')?->name ?? 'Unknown language', "\n"; +``` + +Output: -echo $language->name; -echo $language->type->value; +```text +name=Twig type=template +Unknown language ``` Exact filenames such as `Dockerfile` and `.gitignore` are checked first. Otherwise, the registry tests extensions from right to left. A compound name therefore falls back until a registered suffix matches. +Keep `$language` from the first example when inspecting its metadata below. + ## Inspect the result ```php diff --git a/docs/index.md b/docs/index.md index e7d27c2..957ebc2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,27 +1,23 @@ # Alto Language -Alto Language provides structured metadata for 62 programming and document -languages: extensions, aliases, exact filenames, relationships, and syntax -markers. +Alto Language resolves immutable metadata for 62 programming and document +languages from slugs, aliases, extensions, and exact filenames. ```php use Alto\Language\Languages; $language = Languages::fromFilename('src/Example.php'); - -echo $language?->name; // PHP +echo $language?->name; ``` -## Introduction - -- [Installation](installation.md): install the dependency-free package. -- [Getting started](getting-started.md): resolve a file and inspect its language. - -## Languages +The result is `PHP`. The package returns registered metadata, syntax markers, +and language relationships. It does not inspect source contents or calculate a +detection confidence score. -- [Lookup](lookup.md): resolve slugs, aliases, extensions, and filenames. -- [Catalog](catalog.md): browse and filter the bundled definitions. -- [Definitions](definitions.md): inspect metadata and register application languages. +## Documentation -The package returns metadata. It does not inspect file contents or calculate a -confidence score. +- [Installation](installation.md) +- [Getting started](getting-started.md) +- [Lookup](lookup.md) +- [Catalog](catalog.md) +- [Definitions](definitions.md) diff --git a/docs/lookup.md b/docs/lookup.md index 25d09f9..9b80198 100644 --- a/docs/lookup.md +++ b/docs/lookup.md @@ -42,3 +42,37 @@ $language = $registry->fromFilename('example.ts'); `LanguageRegistry` exposes the same lookup, catalog, and relationship methods without global state. Prefer it in services that use dependency injection. + +## Check the lookup boundary + +This standalone example shows case and suffix behavior without reading any file: + +```php + %s\n", $filename, Languages::fromFilename($filename)?->slug ?? 'unknown'); +} +printf("alias JS => %s\n", Languages::fromAlias('JS')?->slug); +printf("extension .PHP => %s\n", Languages::fromExtension('.PHP')?->slug); +``` + +Output: + +```text +Dockerfile => dockerfile +dockerfile => unknown +home.html.twig => twig +settings.unknown => unknown +alias JS => javascript +extension .PHP => php +``` + +If a lookup returns `null`, choose an application fallback or register metadata +for that language. Language does not examine content or calculate detection +confidence; use content detection in a separate component if the filename is not +enough.