diff --git a/docs/docs/getting-started/quick-start.md b/docs/docs/getting-started/quick-start.md index 87deebc301..d08e27c167 100644 --- a/docs/docs/getting-started/quick-start.md +++ b/docs/docs/getting-started/quick-start.md @@ -146,7 +146,7 @@ public class Alice { When you create a new module, FTL generates a schema that represents your code. For the examples above, the schema would look like: -``` +```schema module alice { verb echo(String?) String } @@ -250,7 +250,7 @@ Note that the `EchoClient` is generated by FTL and must be imported. Unfortunate When you create a second module that calls the first one, the schema would look like: -``` +```schema module alice { export verb echo(String?) String } diff --git a/docs/docs/reference/cron.md b/docs/docs/reference/cron.md index 28fa011e32..f9de7c04a5 100644 --- a/docs/docs/reference/cron.md +++ b/docs/docs/reference/cron.md @@ -56,7 +56,7 @@ class MyCron { -``` +```schema module example { verb hourly(Unit) Unit +cron "0 * * * *" @@ -107,7 +107,7 @@ class MyCron { -``` +```schema module example { verb twiceADay(Unit) Unit +cron "12h" @@ -158,7 +158,7 @@ class MyCron { -``` +```schema module example { verb mondays(Unit) Unit +cron "Mon" diff --git a/docs/docs/reference/databases.md b/docs/docs/reference/databases.md index 439e34d730..4552b9e9ca 100644 --- a/docs/docs/reference/databases.md +++ b/docs/docs/reference/databases.md @@ -103,7 +103,7 @@ Note that this will likely change significantly in future once JVM supports SQL In the FTL schema, databases are represented using the `database` keyword with the engine type and name: -``` +```schema module example { // Database declaration database postgres testdb @@ -138,7 +138,6 @@ module example { // Custom verb that uses a database query export verb getUserEmail(Int) String - +calls example.getUser } ``` @@ -303,7 +302,7 @@ func Query(ctx context.Context, db MydbHandle) ([]string, error) { In the FTL schema, the database handle is represented by the `+database calls` annotation on verbs: -``` +```schema module example { // Database declaration database postgres mydb @@ -371,7 +370,7 @@ func GetEmail(ctx context.Context, id int, query GetUserClient) (string, error) In the FTL schema, the generated query clients are represented as verbs with the `+database calls` and `+sql query` annotations: -``` +```schema module example { // Database declaration database postgres testdb diff --git a/docs/docs/reference/externaltypes.md b/docs/docs/reference/externaltypes.md index 3a8e09c7dd..611dd38cac 100644 --- a/docs/docs/reference/externaltypes.md +++ b/docs/docs/reference/externaltypes.md @@ -144,7 +144,7 @@ You can also specify mappings for other runtimes: In the FTL schema, external types are represented as type aliases with the `+typemap` annotation: -``` +```schema module example { // External type widened to Any typealias FtlType Any diff --git a/docs/docs/reference/ingress.md b/docs/docs/reference/ingress.md index 2337feea3a..fb7eef0cea 100644 --- a/docs/docs/reference/ingress.md +++ b/docs/docs/reference/ingress.md @@ -236,7 +236,7 @@ Under the hood these HTTP invocations are being mapped to verbs that take a `bui In the FTL schema, HTTP ingress is represented by the `+ingress` annotation on verbs: -``` +```schema module example { data GetRequestPathParams { userId String diff --git a/docs/docs/reference/pubsub.md b/docs/docs/reference/pubsub.md index ff1716c13d..6e5aaaeb29 100644 --- a/docs/docs/reference/pubsub.md +++ b/docs/docs/reference/pubsub.md @@ -83,7 +83,7 @@ interface InvoicesTopic extends WriteableTopic { -``` +```schema module payments { // The Invoice data type that will be published to the topic data Invoice { @@ -183,7 +183,7 @@ interface InvoicesTopic extends WriteableTopic { -``` +```schema module payments { // The Invoice data type that will be published to the topic data Invoice { @@ -238,7 +238,7 @@ void publishInvoice(InvoiceRequest request, InvoicesTopic topic) throws Exceptio -``` +```schema module payments { data InvoiceRequest { invoiceNo String @@ -330,14 +330,17 @@ interface InvoicesTopic extends ConsumableTopic {} -``` +```schema module payments { + data InvoiceRequest { + invoiceNo String + } + data Invoice { invoiceNo String } - // The topic that is being subscribed to - export topic invoices payments.Invoice + topic invoices payments.Invoice // A verb that subscribes to the invoices topic verb sendInvoiceEmail(payments.Invoice) Unit diff --git a/docs/docs/reference/retries.md b/docs/docs/reference/retries.md index 02d0961d22..62d2421b42 100644 --- a/docs/docs/reference/retries.md +++ b/docs/docs/reference/retries.md @@ -161,7 +161,7 @@ public void recoverPaymentProcessing(CatchRequest req) { In the FTL schema, retry policies are represented by the `+retry` annotation on verbs: -``` +```schema module example { data Invoice {} diff --git a/docs/docs/reference/secretsconfig.md b/docs/docs/reference/secretsconfig.md index 4603e68c57..2cfb2fe81f 100644 --- a/docs/docs/reference/secretsconfig.md +++ b/docs/docs/reference/secretsconfig.md @@ -69,15 +69,12 @@ HelloResponse hello(HelloRequest helloRequest, @Config("defaultUser") String def In the FTL schema, configuration values are declared as follows: -``` +```schema module example { - // Configuration declaration - config apiUrl String - config defaultUser example.Username + config defaultUser String - // Using configuration in a verb - verb hello(example.HelloRequest) example.HelloResponse - +config defaultUser + verb hello(Unit) String + +config example.defaultUser } ``` @@ -145,7 +142,7 @@ HelloResponse hello(HelloRequest helloRequest, @Secret("apiKey") String apiKey) In the FTL schema, secrets are declared as follows: -``` +```schema module example { // Secret declaration secret apiToken String diff --git a/docs/docs/reference/types.md b/docs/docs/reference/types.md index 4c55e4c40b..20296b17b1 100644 --- a/docs/docs/reference/types.md +++ b/docs/docs/reference/types.md @@ -88,7 +88,7 @@ In the FTL schema, these are the primitive types that can be used directly: | `[T]` | Array of type T | Example usage in schema: -``` +```schema module example { data Person { name String @@ -149,7 +149,7 @@ public class Person { In the FTL schema, data structures are defined using the `data` keyword: -``` +```schema module example { data Person { name String @@ -160,7 +160,7 @@ module example { Fields can have optional values by adding a `?` suffix: -``` +```schema module example { data Person { name String @@ -217,7 +217,7 @@ public class Pair { In the FTL schema, generic types are defined with type parameters: -``` +```schema module example { data Pair { first T @@ -228,7 +228,7 @@ module example { Generic types can be used in other type definitions: -``` +```schema module example { data Pair { first T @@ -290,7 +290,7 @@ class Dog() : Animal In the FTL schema, sum types (type enums) are represented as a union of types: -``` +```schema module example { data Cat {} @@ -305,7 +305,7 @@ module example { When used in other types or verbs, the sum type can be referenced directly: -``` +```schema module example { verb processAnimal(example.Animal) Unit } @@ -402,7 +402,7 @@ public enum Status { In the FTL schema, value enums are represented as an enum with string or integer values: -``` +```schema module example { enum Colour: String { Red = "red" @@ -464,7 +464,7 @@ public class UserID { In the FTL schema, type aliases are defined using the `typealias` keyword: -``` +```schema module example { typealias UserID String } @@ -472,7 +472,7 @@ module example { Type aliases can be used in data structures: -``` +```schema module example { typealias UserID String diff --git a/docs/docs/reference/verbs.md b/docs/docs/reference/verbs.md index edd57b7865..157876fd2c 100644 --- a/docs/docs/reference/verbs.md +++ b/docs/docs/reference/verbs.md @@ -88,7 +88,7 @@ public class EchoClass { In the FTL schema, verbs are declared with their input and output types: -``` +```schema module example { data EchoRequest {} @@ -100,7 +100,7 @@ module example { Verbs can be exported to make them callable from other modules: -``` +```schema module example { export verb echo(example.EchoRequest) example.EchoResponse } @@ -190,7 +190,7 @@ public interface TimeClient { In the FTL schema, verb calls are represented by the `+calls` annotation: -``` +```schema module echo { data EchoRequest {} diff --git a/docs/docs/reference/visibility.md b/docs/docs/reference/visibility.md index 524f61145e..1c927259d7 100644 --- a/docs/docs/reference/visibility.md +++ b/docs/docs/reference/visibility.md @@ -71,7 +71,7 @@ TimeResponse time() { In the FTL schema, exported declarations are prefixed with the `export` keyword: -``` +```schema module example { export data TimeResponse { time Time @@ -87,7 +87,7 @@ module example { Non-exported declarations are visible only within their module: -``` +```schema module example { data InternalConfig { setting String diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 1d92cdbe6b..9529d11b7f 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -137,7 +137,7 @@ const config: Config = { prism: { theme: prismThemes.github, darkTheme: prismThemes.dracula, - additionalLanguages: ['java', 'kotlin', 'bash', 'hcl'], + additionalLanguages: ['java', 'kotlin', 'bash', 'hcl', 'schema'], }, } satisfies Preset.ThemeConfig, } diff --git a/docs/src/theme/prism-include-languages.ts b/docs/src/theme/prism-include-languages.ts new file mode 100644 index 0000000000..1b6a69d295 --- /dev/null +++ b/docs/src/theme/prism-include-languages.ts @@ -0,0 +1,75 @@ +import siteConfig from '@generated/docusaurus.config'; +import type * as PrismNamespace from 'prismjs'; +import type {Optional} from 'utility-types'; + +export default function prismIncludeLanguages( + PrismObject: typeof PrismNamespace, +): void { + const { + themeConfig: {prism}, + } = siteConfig; + const {additionalLanguages} = prism as {additionalLanguages: string[]}; + + // Prism components work on the Prism instance on the window, while prism- + // react-renderer uses its own Prism instance. We temporarily mount the + // instance onto window, import components to enhance it, then remove it to + // avoid polluting global namespace. + // You can mutate PrismObject: registering plugins, deleting languages... As + // long as you don't re-assign it + + const PrismBefore = globalThis.Prism; + globalThis.Prism = PrismObject; + + additionalLanguages.forEach((lang) => { + if (lang === 'php') { + // eslint-disable-next-line global-require + require('prismjs/components/prism-markup-templating.js'); + } + + // Skip loading schema from prismjs since we have our custom implementation + if (lang !== 'schema') { + // eslint-disable-next-line global-require, import/no-dynamic-require + require(`prismjs/components/prism-${lang}`); + } + }); + + // Define custom schema language directly + PrismObject.languages.schema = { + 'comment': { + pattern: /(^|[^\\])\/\/.*|\/\*[\s\S]*?(?:\*\/|$)/, + lookbehind: true, + greedy: true + }, + 'string': { + pattern: /(["'])(?:\\(?:\r\n|[\s\S])|(?!\1)[^\\\r\n])*\1/, + greedy: true + }, + 'keyword': /\b(?:module|export|data|verb|topic|enum|typealias|builtin|config|database|Unit|Time|Int|String|Bool|from|calls|publish|subscribe|ingress|cron|migration|query|column|alias|json|sql|exec|many)\b/, + 'operator': /[<>]=?|[!=]=?=?|--?|\+\+?|&&?|\|\|?|[?*/~^%]/, + 'punctuation': /[{}[\];(),.:]/, + 'boolean': /\b(?:true|false)\b/, + 'number': /\b0x[\da-f]+\b|(?:\b\d+(?:\.\d*)?|\B\.\d+)(?:e[+-]?\d+)?\b/i, + 'directive': { + pattern: /\+[a-zA-Z][a-zA-Z0-9_]*/, + alias: 'function' + }, + 'type': { + pattern: /\b(?:GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\b/, + alias: 'builtin' + }, + 'special-char': { + pattern: /\?|\*/, + alias: 'important' + }, + 'path-pattern': { + pattern: /\/[a-zA-Z0-9_/{}.-]+/, + alias: 'string' + } + }; + + // Clean up and eventually restore former globalThis.Prism object (if any) + delete (globalThis as Optional).Prism; + if (typeof PrismBefore !== 'undefined') { + globalThis.Prism = PrismObject; + } +}