Skip to content

Commit

Permalink
Replace deprecated 'headerFooter' by 'standalone'
Browse files Browse the repository at this point in the history 
* Replace headerFooter methods in OptionsBuild & Options
* Update referenes to the old methods
* Added 'standalone' description to docs
* Re-ordered options in docs to follow alphabetical order
* Remove some unnecessary throws from tests
* Add missing '@deprecated' to templateDir method

Fixes asciidoctor#1160
  • Loading branch information
@abelsromero
abelsromero committed Apr 5, 2023
1 parent 229a0f8 commit af39c81
Show file tree
Hide file tree
Showing 52 changed files with 295 additions and 274 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.adoc
View file
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
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";
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
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
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
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
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
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
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
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
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
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
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
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
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
18 changes: 9 additions & 9 deletions ...roovy/org/asciidoctor/extension/WhenAJavaExtensionGroupIsRegisteredWithAnnotations.groovy
View file
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ And even more infos on manpage:git[7].
def "a docinfoprocessor should be configurable via the Location annotation"() {
when:
asciidoctor.createGroup().docinfoProcessor(AnnotatedDocinfoProcessor).register()
String result = asciidoctor.convert(DOCUMENT, OptionsBuilder.options().headerFooter(true).safe(SafeMode.SERVER))
String result = asciidoctor.convert(DOCUMENT, OptionsBuilder.options().standalone(true).safe(SafeMode.SERVER))

then:
Document doc = Jsoup.parse(result, UTF8)
Expand All @@ -102,7 +102,7 @@ And even more infos on manpage:git[7].
def "a docinfoprocessor instance should be configurable via the Location annotation"() {
when:
asciidoctor.createGroup().docinfoProcessor(new AnnotatedDocinfoProcessor()).register()
String result = asciidoctor.convert(DOCUMENT, OptionsBuilder.options().headerFooter(true).safe(SafeMode.SERVER))
String result = asciidoctor.convert(DOCUMENT, OptionsBuilder.options().standalone(true).safe(SafeMode.SERVER))

then:
Document doc = Jsoup.parse(result, UTF8)
Expand All @@ -114,7 +114,7 @@ And even more infos on manpage:git[7].
def "a docinfoprocessor instance can override the annotation from footer to header"() {
when:
asciidoctor.createGroup().docinfoProcessor(new AnnotatedDocinfoProcessor(LocationType.HEADER)).register()
String result = asciidoctor.convert(DOCUMENT, OptionsBuilder.options().headerFooter(true).safe(SafeMode.SERVER))
String result = asciidoctor.convert(DOCUMENT, OptionsBuilder.options().standalone(true).safe(SafeMode.SERVER))

then:
Document doc = Jsoup.parse(result, UTF8)
Expand All @@ -124,7 +124,7 @@ And even more infos on manpage:git[7].
def "a docinfoprocessor instance can override the annotation from footer to footer"() {
when:
asciidoctor.createGroup().docinfoProcessor(new AnnotatedDocinfoProcessor(LocationType.FOOTER)).register()
String result = asciidoctor.convert(DOCUMENT, OptionsBuilder.options().headerFooter(true).safe(SafeMode.SERVER))
String result = asciidoctor.convert(DOCUMENT, OptionsBuilder.options().standalone(true).safe(SafeMode.SERVER))

then:
Document doc = Jsoup.parse(result, UTF8)
Expand All @@ -136,7 +136,7 @@ And even more infos on manpage:git[7].

when:
asciidoctor.createGroup().blockMacro(AnnotatedBlockMacroProcessor).register()
String result = asciidoctor.convert(BLOCK_MACRO_DOCUMENT, OptionsBuilder.options().headerFooter(false))
String result = asciidoctor.convert(BLOCK_MACRO_DOCUMENT, OptionsBuilder.options().standalone(false))

then:
result.contains(AnnotatedBlockMacroProcessor.RESULT)
Expand All @@ -148,7 +148,7 @@ And even more infos on manpage:git[7].

when:
asciidoctor.createGroup().block(AnnotatedBlockProcessor).register()
String result = asciidoctor.convert(BLOCK_DOCUMENT, OptionsBuilder.options().headerFooter(false))
String result = asciidoctor.convert(BLOCK_DOCUMENT, OptionsBuilder.options().standalone(false))

then:
result.contains(DO_NOT_TOUCH_THIS)
Expand All @@ -162,7 +162,7 @@ And even more infos on manpage:git[7].

when:
asciidoctor.createGroup().block(new AnnotatedBlockProcessor('dummy', 'yell2')).register()
String result = asciidoctor.convert(BLOCK_DOCUMENT_2, OptionsBuilder.options().headerFooter(false))
String result = asciidoctor.convert(BLOCK_DOCUMENT_2, OptionsBuilder.options().standalone(false))

then:
result.contains(DO_NOT_TOUCH_THIS)
Expand All @@ -173,7 +173,7 @@ And even more infos on manpage:git[7].
def "when registering an InlineMacroProcessor class with long format it should be configurable via annotations"() {
when:
asciidoctor.createGroup().inlineMacro(AnnotatedLongInlineMacroProcessor).register()
String result = asciidoctor.convert(INLINE_MACRO_DOCUMENT, OptionsBuilder.options().headerFooter(false))
String result = asciidoctor.convert(INLINE_MACRO_DOCUMENT, OptionsBuilder.options().standalone(false))

then:
Document doc = Jsoup.parse(result, UTF8)
Expand All @@ -184,7 +184,7 @@ And even more infos on manpage:git[7].
def "when registering an InlineMacroProcessor class with regexp it should be configurable via annotations"() {
when:
asciidoctor.createGroup().inlineMacro(AnnotatedRegexpInlineMacroProcessor).register()
String result = asciidoctor.convert(INLINE_MACRO_REGEXP_DOCUMENT, OptionsBuilder.options().headerFooter(false))
String result = asciidoctor.convert(INLINE_MACRO_REGEXP_DOCUMENT, OptionsBuilder.options().standalone(false))

then:
Document doc = Jsoup.parse(result, UTF8)
Expand Down
Loading

0 comments on commit af39c81

Please sign in to comment.