From 74d17007ed1245e77d9833e8015cf94b6616b4e7 Mon Sep 17 00:00:00 2001 From: Deborah Date: Sat, 4 Sep 2021 16:11:21 +0100 Subject: [PATCH 1/5] add list of valid context names to findBy docs Proposal: add a list of valid context names to the findBy docs. I've added all the names I've found so far. However, if this docs repo PR is accepted (https://github.com/asciidoctor/asciidoc-docs/pull/90), it might be nicer to just add a link to the docs, rather than maintain the list in two places. --- packages/core/src/asciidoctor-core-api.js | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/packages/core/src/asciidoctor-core-api.js b/packages/core/src/asciidoctor-core-api.js index 89e5c9788..37befaa6f 100644 --- a/packages/core/src/asciidoctor-core-api.js +++ b/packages/core/src/asciidoctor-core-api.js @@ -684,6 +684,25 @@ AbstractBlock.prototype.convert = function () { * that match the specified selector (context, style, id, and/or role). * If a function block is given, it's used as an additional filter. * If no selector or function block is supplied, all block-level nodes in the tree are returned. + * Valid context names include: + * document + * section + * paragraph + * image + * dlist (description list) + * ulist + * olist + * list_item + * literal + * listing + * admonition + * sidebar + * example + * open + * pass (a passthrough block) + * table + * thematic_break (horizontal rule) + * page_break * @param {Object} [selector] * @param {function} [block] * @example From 42fba6d1b0a5d44467852acd94d5d543e600d282 Mon Sep 17 00:00:00 2001 From: Guillaume Grossetie Date: Mon, 31 Oct 2022 14:01:06 +0100 Subject: [PATCH 2/5] update context list and add typescript type def --- packages/core/src/asciidoctor-core-api.js | 50 +++++---- packages/core/types/index.d.ts | 120 +++++++++++++++++++++- packages/core/types/tests.ts | 3 +- 3 files changed, 152 insertions(+), 21 deletions(-) diff --git a/packages/core/src/asciidoctor-core-api.js b/packages/core/src/asciidoctor-core-api.js index 37befaa6f..d7a10d063 100644 --- a/packages/core/src/asciidoctor-core-api.js +++ b/packages/core/src/asciidoctor-core-api.js @@ -684,25 +684,37 @@ AbstractBlock.prototype.convert = function () { * that match the specified selector (context, style, id, and/or role). * If a function block is given, it's used as an additional filter. * If no selector or function block is supplied, all block-level nodes in the tree are returned. - * Valid context names include: - * document - * section - * paragraph - * image - * dlist (description list) - * ulist - * olist - * list_item - * literal - * listing - * admonition - * sidebar - * example - * open - * pass (a passthrough block) - * table - * thematic_break (horizontal rule) - * page_break + * Valid context names include: + * + * @see https://docs.asciidoctor.org/asciidoc/latest/blocks/#summary-of-built-in-contexts * @param {Object} [selector] * @param {function} [block] * @example diff --git a/packages/core/types/index.d.ts b/packages/core/types/index.d.ts index e6c977fa8..bba4b882b 100644 --- a/packages/core/types/index.d.ts +++ b/packages/core/types/index.d.ts @@ -605,7 +605,123 @@ export namespace Asciidoctor { } } + /** + * List of the contexts of all the built-in blocks in AsciiDoc. + * @see https://docs.asciidoctor.org/asciidoc/latest/blocks/#summary-of-built-in-contexts + */ + enum BuiltInContext { + /** + * One of five admonition blocks. + */ + Admonition = "admonition", + /** + * An audio block. + */ + Audio = "audio", + /** + * A callout list. + */ + CalloutList = "colist", + /** + * A description list. + */ + DescriptionList = "dlist", + /** + * The top-level document or the document in an AsciiDoc table cell. + */ + Document = "document", + /** + * An example block. + */ + Example = "example", + /** + * A discrete heading. + */ + FloatingTitle = "floating_title", + /** + * An image block. + */ + Image = "image", + /** + * An item in an ordered, unordered, or description list (only relevant inside a list or description list block). In a description list, this block is used to represent the term and the description. + */ + ListItem = "list_item", + /** + * A listing block. + */ + Listing = "list_item", + /** + * A literal block. + */ + Literal = "list_item", + /** + * An ordered list. + */ + OrderedList = "olist", + /** + * An open block. + */ + Open = "open", + /** + * A page break. + */ + PageBreak = "page_break", + /** + * A paragraph. + */ + Paragraph = "paragraph", + /** + * A passthrough block. + */ + Passthrough = "pass", + /** + * The preamble of the document. + */ + Preamble = "preamble", + /** + * A quote block (aka blockquote). + */ + Quote = "quote", + /** + * A section. May also be a part, chapter, or special section. + */ + Section = "section", + /** + * A sidebar block. + */ + Sidebar = "sidebar", + /** + * A table block. + */ + Table = "table", + /** + * A table cell (only relevant inside a table block). + */ + TableCell = "table_cell", + /** + * A thematic break (aka horizontal rule). + */ + ThematicBreak = "thematic_break", + /** + * A TOC block. + */ + TableOfContent = "toc", + /** + * An unordered list. + */ + UnorderedList = "ulist", + /** + * An unordered list. + */ + Verse = "verse", + /** + * A video block. + */ + Video = "video", + } + interface Selector { + context: BuiltInContext | string [key: string]: any; } @@ -2060,7 +2176,7 @@ export namespace Asciidoctor { /** * Get the location in the AsciiDoc source where this block begins. - * @returns the style for this block + * @returns the style for this blockfindBy */ getSourceLocation(): Cursor; @@ -2134,6 +2250,8 @@ export namespace Asciidoctor { * that match the specified selector (context, style, id, and/or role). * If a function block is given, it's used as an additional filter. * If no selector or function block is supplied, all block-level nodes in the tree are returned. + * Valid context names include {@link BuiltInContext}. + * * @example * doc.findBy({'context': 'section'}); * // => { level: 0, title: "Hello, AsciiDoc!", blocks: 0 } diff --git a/packages/core/types/tests.ts b/packages/core/types/tests.ts index 2dd8ea428..4c654e6c9 100644 --- a/packages/core/types/tests.ts +++ b/packages/core/types/tests.ts @@ -525,6 +525,7 @@ const result = docWithParagraphs.findBy((candidate) => { } else if (ctx === 'paragraph') { return true; } + return false; }); assert(result.length === 2); assert(result[0].getContext() === 'paragraph'); @@ -1233,7 +1234,7 @@ a| :foo: foo AsciiDoc cell |===`); -const tableWithAsciiDocCell = docWithAsciiDocCell.findBy({context: 'table'})[0] as Asciidoctor.Table; +const tableWithAsciiDocCell = docWithAsciiDocCell.findBy({context: Asciidoctor.BuiltInContext.Table})[0] as Asciidoctor.Table; const normalCell = tableWithAsciiDocCell.getBodyRows()[0][0]; const asciidocCell = tableWithAsciiDocCell.getBodyRows()[1][0]; assert(typeof normalCell.getInnerDocument() === 'undefined'); From 866ecd06aa5c77ae3647959e438b5bee22e64a72 Mon Sep 17 00:00:00 2001 From: Guillaume Grossetie Date: Mon, 31 Oct 2022 14:02:05 +0100 Subject: [PATCH 3/5] fix unintented copy/paste --- packages/core/types/index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/core/types/index.d.ts b/packages/core/types/index.d.ts index bba4b882b..63598d667 100644 --- a/packages/core/types/index.d.ts +++ b/packages/core/types/index.d.ts @@ -2176,7 +2176,7 @@ export namespace Asciidoctor { /** * Get the location in the AsciiDoc source where this block begins. - * @returns the style for this blockfindBy + * @returns the style for this block */ getSourceLocation(): Cursor; From c207e3109c21a493ee2d6f8e19f15662f7a1d9f8 Mon Sep 17 00:00:00 2001 From: Guillaume Grossetie Date: Mon, 31 Oct 2022 18:32:11 +0100 Subject: [PATCH 4/5] Should not return undefined --- packages/core/types/tests.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/core/types/tests.ts b/packages/core/types/tests.ts index 4c654e6c9..8fbb3087e 100644 --- a/packages/core/types/tests.ts +++ b/packages/core/types/tests.ts @@ -1184,6 +1184,7 @@ const outerParagraphs = docWithExample.findBy((candidate) => { } else if (ctx === 'paragraph') { return true; } + return false; }); assert(outerParagraphs.length === 2); assert(outerParagraphs[0].getContext() === 'paragraph'); From e5c203e2351da3b7add02c472653d3dab2e0160f Mon Sep 17 00:00:00 2001 From: Guillaume Grossetie Date: Mon, 31 Oct 2022 19:13:33 +0100 Subject: [PATCH 5/5] add BuiltInContext enum --- packages/core/src/asciidoctor-core-api.js | 115 ++++++++++++++++++++++ packages/core/types/index.d.ts | 2 + packages/core/types/tests.ts | 14 +-- 3 files changed, 124 insertions(+), 7 deletions(-) diff --git a/packages/core/src/asciidoctor-core-api.js b/packages/core/src/asciidoctor-core-api.js index d7a10d063..860db4057 100644 --- a/packages/core/src/asciidoctor-core-api.js +++ b/packages/core/src/asciidoctor-core-api.js @@ -679,6 +679,121 @@ AbstractBlock.prototype.convert = function () { return this.$convert() } +/** + * @namespace + * @extends BuiltInContext + */ +Opal.Asciidoctor.BuiltInContext = { + /** + * One of five admonition blocks. + */ + Admonition: 'admonition', + /** + * An audio block. + */ + Audio: 'audio', + /** + * A callout list. + */ + CalloutList: 'colist', + /** + * A description list. + */ + DescriptionList: 'dlist', + /** + * The top-level document or the document in an AsciiDoc table cell. + */ + Document: 'document', + /** + * An example block. + */ + Example: 'example', + /** + * A discrete heading. + */ + FloatingTitle: 'floating_title', + /** + * An image block. + */ + Image: 'image', + /** + * An item in an ordered, unordered, or description list (only relevant inside a list or description list block). In a description list, this block is used to represent the term and the description. + */ + ListItem: 'list_item', + /** + * A listing block. + */ + Listing: 'list_item', + /** + * A literal block. + */ + Literal: 'list_item', + /** + * An ordered list. + */ + OrderedList: 'olist', + /** + * An open block. + */ + Open: 'open', + /** + * A page break. + */ + PageBreak: 'page_break', + /** + * A paragraph. + */ + Paragraph: 'paragraph', + /** + * A passthrough block. + */ + Passthrough: 'pass', + /** + * The preamble of the document. + */ + Preamble: 'preamble', + /** + * A quote block (aka blockquote). + */ + Quote: 'quote', + /** + * A section. May also be a part, chapter, or special section. + */ + Section: 'section', + /** + * A sidebar block. + */ + Sidebar: 'sidebar', + /** + * A table block. + */ + Table: 'table', + /** + * A table cell (only relevant inside a table block). + */ + TableCell: 'table_cell', + /** + * A thematic break (aka horizontal rule). + */ + ThematicBreak: 'thematic_break', + /** + * A TOC block. + */ + TableOfContent: 'toc', + /** + * An unordered list. + */ + UnorderedList: 'ulist', + /** + * An unordered list. + */ + Verse: 'verse', + /** + * A video block. + */ + Video: 'video' +} + /** * Query for all descendant block-level nodes in the document tree * that match the specified selector (context, style, id, and/or role). diff --git a/packages/core/types/index.d.ts b/packages/core/types/index.d.ts index 63598d667..99bfe921f 100644 --- a/packages/core/types/index.d.ts +++ b/packages/core/types/index.d.ts @@ -3796,6 +3796,8 @@ export class Asciidoctor { */ getVersion(): string; + BuiltInContext: typeof Asciidoctor.BuiltInContext; + Block: typeof Asciidoctor.Block; Section: typeof Asciidoctor.Section; diff --git a/packages/core/types/tests.ts b/packages/core/types/tests.ts index 8fbb3087e..7335f4dc8 100644 --- a/packages/core/types/tests.ts +++ b/packages/core/types/tests.ts @@ -1115,10 +1115,10 @@ assert(rowsBySection[2][0] === 'foot'); const docWithParagraph = processor.load(`paragraph`); const paragraphBlock = docWithParagraph.getBlocks()[0]; -assert(paragraphBlock.resolveSubstitutions('attributes+', 'block')[0] === 'attributes'); +assert(paragraphBlock.resolveSubstitutions('attributes+', 'block')?.[0] === 'attributes'); const blockSubs1 = paragraphBlock.resolveBlockSubstitutions('specialchars,attributes,quotes,replacements,macros,post_replacements', 'block'); assert(blockSubs1.length === 6); -assert(blockSubs1[0] === 'specialcharacters'); +assert(blockSubs1?.[0] === 'specialcharacters'); assert(blockSubs1[1] === 'attributes'); assert(blockSubs1[2] === 'quotes'); assert(blockSubs1[3] === 'replacements'); @@ -1126,13 +1126,13 @@ assert(blockSubs1[4] === 'macros'); assert(blockSubs1[5] === 'post_replacements'); const blockSubs2 = paragraphBlock.resolveBlockSubstitutions('attributes+,+replacements,-callouts', ['verbatim', 'quotes', 'callouts']); assert(blockSubs2.length === 4); -assert(blockSubs2[0] === 'attributes'); +assert(blockSubs2?.[0] === 'attributes'); assert(blockSubs2[1] === 'verbatim'); assert(blockSubs2[2] === 'quotes'); assert(blockSubs2[3] === 'replacements'); const blockSubs3 = paragraphBlock.resolveBlockSubstitutions('normal'); assert(blockSubs3.length === 6); -assert(blockSubs3[0] === 'specialcharacters'); +assert(blockSubs3?.[0] === 'specialcharacters'); assert(blockSubs3[1] === 'quotes'); assert(blockSubs3[2] === 'attributes'); assert(blockSubs3[3] === 'replacements'); @@ -1140,10 +1140,10 @@ assert(blockSubs3[4] === 'macros'); assert(blockSubs3[5] === 'post_replacements'); const blockSubs4 = paragraphBlock.resolvePassSubstitutions('macros'); assert(blockSubs4.length === 1); -assert(blockSubs4[0] === 'macros'); +assert(blockSubs4?.[0] === 'macros'); const blockSubs5 = paragraphBlock.resolvePassSubstitutions('verbatim'); assert(blockSubs5.length === 1); -assert(blockSubs5[0] === 'specialcharacters'); +assert(blockSubs5?.[0] === 'specialcharacters'); const docWithImages = processor.load(` [#img-sunset] @@ -1235,7 +1235,7 @@ a| :foo: foo AsciiDoc cell |===`); -const tableWithAsciiDocCell = docWithAsciiDocCell.findBy({context: Asciidoctor.BuiltInContext.Table})[0] as Asciidoctor.Table; +const tableWithAsciiDocCell = docWithAsciiDocCell.findBy({context: processor.BuiltInContext.Table})[0] as Asciidoctor.Table; const normalCell = tableWithAsciiDocCell.getBodyRows()[0][0]; const asciidocCell = tableWithAsciiDocCell.getBodyRows()[1][0]; assert(typeof normalCell.getInnerDocument() === 'undefined');