Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Replace deprecated 'headerFooter' by 'standalone' #1161

Merged
merged 2 commits into from
Apr 7, 2023
Merged

Replace deprecated 'headerFooter' by 'standalone' #1161

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
af39c81
Replace deprecated 'headerFooter' by 'standalone'
abelsromero Apr 5, 2023
c9d92cc
Remove unnecessary GH action v2.5.x branch reference
abelsromero Apr 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .github/workflows/continuous-integration.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@ on:
pull_request:
branches:
- main
- v2.5.x
schedule:
- cron: '0 0 * * *'

Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ Improvement::
* Set Java 11 as the minimal version (#1151) (@abelsromero)
* Create `asciidoctorj-cli` module to prevent unnecessary dependencies to asciidoctorj jar consumers (#1149)
* Add required `--add-opens` to cli launch script to remove Jdk warnings (#1155) (@abelsromero)
* Rename deprecated `headerFooter` option to the new `standalone` with same functionality (#1155) (@abelsromero)

Bug Fixes::

Expand Down
22 changes: 14 additions & 8 deletions asciidoctorj-api/src/main/java/org/asciidoctor/Options.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,15 @@
import java.util.List;
import java.util.Map;

/**
* AsciidoctorJ conversion options. Each one maps to an option in Asciidoctor.
* See https://docs.asciidoctor.org/asciidoctor/latest/api/options/ for further
* details.
*/
public class Options {

public static final String IN_PLACE = "in_place";
public static final String ATTRIBUTES = "attributes";
public static final String HEADER_FOOTER = "header_footer";
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we want to at least keep the constant?
Even if the option is not recommended, Asciidoctor itself still handles it.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought about it, my rationale was that if this is not the recommended way, we should not make it easy to use. Users can still use it as a String if they want, but since we had no references in the current code we could remove it.

We could add it back, I admit I am being very strict with the "let's clean thing now that we can to breaking changes" 😄

public static final String TEMPLATE_DIRS = "template_dirs";
public static final String TEMPLATE_ENGINE = "template_engine";
public static final String TO_FILE = "to_file";
Expand Down Expand Up @@ -72,18 +76,20 @@ public void setAttributes(Map<String, Object> attributes) {
/**
* Toggle including header and footer into the output.
*
* @param headerFooter If <code>true</true>, include header and footer into the output,
* otherwise exclude them. This overrides any output-specific defaults.
*
* @param standalone <code>true</code> to generate a standalone output document
* (which includes the shell around the body content, such
* as the header and footer).
* Defaults to <code>true</code> when converting a file only,
* otherwise is <code>false</code>.
*/
public void setHeaderFooter(boolean headerFooter) {
this.options.put(HEADER_FOOTER, headerFooter);
public void setStandalone(boolean standalone) {
this.options.put(STANDALONE, standalone);
}

public void setTemplateDirs(String... templateDirs) {

if (!this.options.containsKey(TEMPLATE_DIRS)) {
this.options.put(TEMPLATE_DIRS, new ArrayList<Object>());
this.options.put(TEMPLATE_DIRS, new ArrayList<>());
}

List<Object> allTemplateDirs = (List<Object>) this.options.get(TEMPLATE_DIRS);
Expand Down Expand Up @@ -117,7 +123,7 @@ public void setToStream(OutputStream toStream) {
* as the input file, including header and footer into the output. If
* <code>false</code>, return output as a string without any header or
* footer. The default header and footer visibility can be overridden
* using {@link #setHeaderFooter(boolean)}.
* using {@link #setStandalone(boolean)}.
*
*/
public void setToFile(boolean toFile) {
Expand Down
30 changes: 21 additions & 9 deletions asciidoctorj-api/src/main/java/org/asciidoctor/OptionsBuilder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@
import java.io.OutputStream;
import java.util.Map;

/**
* Fluent Options API for AsciidoctorJ.
*
* @see org.asciidoctor.Options
*/
public class OptionsBuilder {

private final Options options = new Options();
Expand Down Expand Up @@ -37,9 +42,11 @@ public OptionsBuilder backend(String backend) {

/**
* Sets doctype option.
*
* @param docType
* value.
* Valid options are <code>article</code>, <code>book</code>,
* <code>manpage</code> and <code>inline</code>.
* Default <code>article</code>.
*
* @param docType value.
* @return this instance.
*/
public OptionsBuilder docType(String docType) {
Expand All @@ -60,14 +67,17 @@ public OptionsBuilder inPlace(boolean inPlace) {
}

/**
* Sets header footer attribute.
*
* @param headerFooter
* value.
* Sets standalone option.
*
* @param standalone <code>true</code> to generate a standalone output document
* (which includes the shell around the body content, such
* as the header and footer).
* Defaults to <code>true</code> when converting a file only,
* otherwise is <code>false</code>.
* @return this instance.
*/
public OptionsBuilder headerFooter(boolean headerFooter) {
this.options.setHeaderFooter(headerFooter);
public OptionsBuilder standalone(boolean standalone) {
this.options.setStandalone(standalone);
return this;
}

Expand All @@ -79,7 +89,9 @@ public OptionsBuilder headerFooter(boolean headerFooter) {
* @param templateDir
* directory where templates are stored.
* @return this instance.
* @deprecated Use {@link #templateDirs(File...)} instead.
*/
@Deprecated
public OptionsBuilder templateDir(File templateDir) {
this.options.setTemplateDirs(templateDir.getAbsolutePath());
return this;
Expand Down
3 changes: 1 addition & 2 deletions asciidoctorj-core/src/main/java/org/asciidoctor/jruby/internal/AsciidoctorUtils.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,6 @@ private class CliOptions {
}

private AsciidoctorUtils() {
super();
}

public static boolean isOptionWithAttribute(Map<String, Object> options, String attributeName, String attributeValue) {
Expand Down Expand Up @@ -93,7 +92,7 @@ private static List<String> getOptions(Map<String, Object> options) {
optionsAndAttributes.add(options.get(Options.ERUBY).toString());
}

if (options.containsKey(Options.HEADER_FOOTER)) {
if (options.containsKey(Options.STANDALONE)) {
optionsAndAttributes.add(CliOptions.NO_HEADER_FOOTER);
}

Expand Down
8 changes: 4 additions & 4 deletions ...idoctorj-core/src/test/groovy/org/asciidoctor/WhenADocumentContainsADefinitionList.groovy
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Item C:: Another description
'''

when:
Document documentNode = asciidoctor.load(document, OptionsBuilder.options().headerFooter(false).asMap())
Document documentNode = asciidoctor.load(document, OptionsBuilder.options().standalone(false).asMap())

then:
DescriptionList list = documentNode.blocks[0]
Expand Down Expand Up @@ -112,7 +112,7 @@ Item A::

when:
asciidoctor.javaConverterRegistry().register(TestConverter, TestConverter.NAME)
String result = asciidoctor.convert(document, OptionsBuilder.options().backend(TestConverter.NAME).headerFooter(false).asMap())
String result = asciidoctor.convert(document, OptionsBuilder.options().backend(TestConverter.NAME).standalone(false).asMap())

then:
result == '''TEST DOCUMENT
Expand All @@ -134,7 +134,7 @@ Item B::

when:
asciidoctor.javaConverterRegistry().register(TestConverter, TestConverter.NAME)
String result = asciidoctor.convert(document, OptionsBuilder.options().backend(TestConverter.NAME).headerFooter(false).asMap())
String result = asciidoctor.convert(document, OptionsBuilder.options().backend(TestConverter.NAME).standalone(false).asMap())

then:
result == '''TEST DOCUMENT
Expand Down Expand Up @@ -165,7 +165,7 @@ Item A::
doc
}
})
String result = asciidoctor.convert(document, OptionsBuilder.options().headerFooter(false).asMap())
String result = asciidoctor.convert(document, OptionsBuilder.options().standalone(false).asMap())

then:
org.jsoup.nodes.Document htmlDoc = Jsoup.parse(result)
Expand Down
6 changes: 3 additions & 3 deletions asciidoctorj-core/src/test/groovy/org/asciidoctor/WhenATableIsLoaded.groovy
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ class WhenATableIsLoaded extends Specification {
'''

when:
Document documentNode = asciidoctor.load(document, OptionsBuilder.options().headerFooter(false).asMap())
Document documentNode = asciidoctor.load(document, OptionsBuilder.options().standalone(false).asMap())
Table tableNode = documentNode.blocks[0]

then:
Expand All @@ -50,7 +50,7 @@ class WhenATableIsLoaded extends Specification {
'''

when:
Document documentNode = asciidoctor.load(document, OptionsBuilder.options().headerFooter(false).asMap())
Document documentNode = asciidoctor.load(document, OptionsBuilder.options().standalone(false).asMap())
Table tableNode = documentNode.blocks[0]

then:
Expand Down Expand Up @@ -78,7 +78,7 @@ The second content cell
'''

when:
Document documentNode = asciidoctor.load(document, OptionsBuilder.options().headerFooter(false).asMap())
Document documentNode = asciidoctor.load(document, OptionsBuilder.options().standalone(false).asMap())
Table tableNode = documentNode.blocks[0]

then:
Expand Down
2 changes: 1 addition & 1 deletion asciidoctorj-core/src/test/groovy/org/asciidoctor/WhenSlimTemplatesAreUsed.groovy
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ class WhenSlimTemplatesAreUsed extends Specification {

def 'the slim paragraph template should be used when rendering a document inline'() {
given:
Options options = options().templateDir(classpath.getResource('src/custom-backends/slim')).toFile(false).headerFooter(false).get()
Options options = options().templateDir(classpath.getResource('src/custom-backends/slim')).toFile(false).standalone(false).get()

String sourceDocument = '''
= Hello World
Expand Down
6 changes: 3 additions & 3 deletions asciidoctorj-core/src/test/groovy/org/asciidoctor/WhenTheSourceShouldBeAccessed.groovy
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@ xxx
doc
}
})
String html = asciidoctor.convert(document, OptionsBuilder.options().headerFooter(false).asMap())
String html = asciidoctor.convert(document, OptionsBuilder.options().standalone(false).asMap())
org.jsoup.nodes.Document doc = Jsoup.parse(html)

then:
Expand Down Expand Up @@ -179,7 +179,7 @@ xxx
doc
}
})
String html = asciidoctor.convert(document, OptionsBuilder.options().headerFooter(false).asMap())
String html = asciidoctor.convert(document, OptionsBuilder.options().standalone(false).asMap())
org.jsoup.nodes.Document doc = Jsoup.parse(html)

then:
Expand Down Expand Up @@ -211,7 +211,7 @@ xxx
doc
}
})
String html = asciidoctor.convert(document, OptionsBuilder.options().headerFooter(false).asMap())
String html = asciidoctor.convert(document, OptionsBuilder.options().standalone(false).asMap())
org.jsoup.nodes.Document doc = Jsoup.parse(html)

then:
Expand Down
4 changes: 2 additions & 2 deletions asciidoctorj-core/src/test/groovy/org/asciidoctor/converter/TableConverterTest.groovy
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ class TableConverterTest extends Specification {
asciidoctor.javaConverterRegistry().register(TableTestConverter, 'tabletestconverter')

when:
String content = asciidoctor.convert(document, OptionsBuilder.options().headerFooter(false).backend('tabletestconverter'))
String content = asciidoctor.convert(document, OptionsBuilder.options().standalone(false).backend('tabletestconverter'))

then:
content.readLines().collect {it - ~/\s+$/ } == '''HELLO TABLE
Expand Down Expand Up @@ -68,7 +68,7 @@ a|
asciidoctor.javaConverterRegistry().register(TableTestConverter, 'tabletestconverter')

when:
String content = asciidoctor.convert(document, OptionsBuilder.options().headerFooter(false).backend('tabletestconverter'))
String content = asciidoctor.convert(document, OptionsBuilder.options().standalone(false).backend('tabletestconverter'))

then:
content.readLines().collect {it - ~/\s+$/ } == '''HELLO ASCIIDOCTOR TABLE
Expand Down
4 changes: 2 additions & 2 deletions ...ore/src/test/groovy/org/asciidoctor/extension/WhenABlockMacroProcessorCreatesAList.groovy
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ list::HelloWorld[]
asciidoctor.javaExtensionRegistry().blockMacro(LISTMACRO_NAME, new ListCreatorBlockMacro('olist'))

when:
String result = asciidoctor.convert(DOCUMENT, OptionsBuilder.options().safe(SafeMode.SAFE).toFile(false).headerFooter(false))
String result = asciidoctor.convert(DOCUMENT, OptionsBuilder.options().safe(SafeMode.SAFE).toFile(false).standalone(false))

then:
noExceptionThrown()
Expand All @@ -57,7 +57,7 @@ list::HelloWorld[]
asciidoctor.javaExtensionRegistry().blockMacro(LISTMACRO_NAME, new ListCreatorBlockMacro('ulist'))

when:
String result = asciidoctor.convert(DOCUMENT, OptionsBuilder.options().safe(SafeMode.SAFE).toFile(false).headerFooter(false))
String result = asciidoctor.convert(DOCUMENT, OptionsBuilder.options().safe(SafeMode.SAFE).toFile(false).standalone(false))

then:
noExceptionThrown()
Expand Down
4 changes: 2 additions & 2 deletions .../src/test/groovy/org/asciidoctor/extension/WhenABlockMacroProcessorCreatesASection.groovy
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ section::HelloWorld[]
asciidoctor.javaExtensionRegistry().blockMacro(BLOCKMACRO_NAME, SectionCreatorBlockMacro)

when:
String result = asciidoctor.convert(DOCUMENT, OptionsBuilder.options().safe(SafeMode.SAFE).toFile(false).headerFooter(true))
String result = asciidoctor.convert(DOCUMENT, OptionsBuilder.options().safe(SafeMode.SAFE).toFile(false).standalone(true))

then:
noExceptionThrown()
Expand All @@ -52,7 +52,7 @@ section::HelloWorld[]
asciidoctor.createGroup().blockMacro(BLOCKMACRO_NAME, SectionCreatorBlockMacro).register()

when:
String result = asciidoctor.convert(DOCUMENT, OptionsBuilder.options().safe(SafeMode.SAFE).toFile(false).headerFooter(true))
String result = asciidoctor.convert(DOCUMENT, OptionsBuilder.options().safe(SafeMode.SAFE).toFile(false).standalone(true))

then:
noExceptionThrown()
Expand Down
2 changes: 1 addition & 1 deletion ...org/asciidoctor/extension/WhenABlockProcessorCreatesABlockThatATreeProcessorVisits.groovy
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ This will be ignored
asciidoctor.javaExtensionRegistry().treeprocessor(BlockVisitor)

when:
asciidoctor.convert(DOCUMENT, OptionsBuilder.options().safe(SafeMode.SAFE).toFile(false).headerFooter(true))
asciidoctor.convert(DOCUMENT, OptionsBuilder.options().safe(SafeMode.SAFE).toFile(false).standalone(true))

then:
notThrown(ClassCastException)
Expand Down
2 changes: 1 addition & 1 deletion ...octorj-core/src/test/groovy/org/asciidoctor/extension/WhenABlockShouldBeDuplicated.groovy
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ This will be ignored
'''

when:
org.jsoup.nodes.Document html = Jsoup.parse(asciidoctor.convert(asciidoctorSource, OptionsBuilder.options().safe(SafeMode.SAFE).headerFooter(false).asMap()))
org.jsoup.nodes.Document html = Jsoup.parse(asciidoctor.convert(asciidoctorSource, OptionsBuilder.options().safe(SafeMode.SAFE).standalone(false).asMap()))

then:
html.select(CLASS_LISTINGBLOCK).get(0).text() == 'This will be ignored'
Expand Down
2 changes: 1 addition & 1 deletion ...-core/src/test/groovy/org/asciidoctor/extension/WhenAJavaExtensionChecksAttributes.groovy
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Check me
def "a BlockProcessor should only get String attribute keys"() {
when:
asciidoctor.javaExtensionRegistry().block(AttributeCheckingBlockProcessor)
asciidoctor.convert(DOCUMENT, OptionsBuilder.options().headerFooter(true).safe(SafeMode.SERVER))
asciidoctor.convert(DOCUMENT, OptionsBuilder.options().standalone(true).safe(SafeMode.SERVER))

then:
noExceptionThrown()
Expand Down
Loading