Skip to content

Commit

Permalink
shrink public API surface in laika.rst.*
Browse files Browse the repository at this point in the history
  • Loading branch information
jenshalm committed Jul 15, 2023
1 parent 76ed269 commit 49c9e70
Show file tree
Hide file tree
Showing 26 changed files with 290 additions and 221 deletions.
4 changes: 2 additions & 2 deletions core/shared/src/main/scala/laika/markdown/ast/elements.scala
Original file line number Diff line number Diff line change
Expand Up @@ -58,8 +58,8 @@ case class HTMLStartTag(name: String, attributes: List[HTMLAttribute], options:
def withOptions(options: Options): HTMLStartTag = copy(options = options)
}

/** Represents an empty element (like `<br/>` or `<hr/>`)
* in case it contains the explicit slash to mark it as closed.
/** Represents an empty element (like `<br/>` or `<hr/>`)
* in case it contains the explicit slash to mark it as closed.
* Otherwise it will be classified as a start tag.
*/
case class HTMLEmptyElement(name: String, attributes: List[HTMLAttribute], options: Options = NoOpt)
Expand Down
4 changes: 2 additions & 2 deletions core/shared/src/main/scala/laika/rst/BaseParsers.scala
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,12 @@ import laika.parse.text.{ CharGroup, Characters }

/** @author Jens Halm
*/
object BaseParsers {
private[laika] object BaseParsers {

/** Set of punctuation characters as supported by transitions (rules) and
* overlines and underlines for header sections.
*/
private[laika] val punctuationChars: NonEmptySet[Char] =
val punctuationChars: NonEmptySet[Char] =
NonEmptySet.of('!', '"', '#', '$', '%', '&', '\'', '(', ')', '[', ']', '{', '}', '*', '+', ',',
'-', '.', ':', ';', '/', '<', '>', '=', '?', '@', '\\', '^', '_', '`', '|', '~')

Expand Down
46 changes: 22 additions & 24 deletions core/shared/src/main/scala/laika/rst/BlockParsers.scala
Original file line number Diff line number Diff line change
Expand Up @@ -48,11 +48,10 @@ import scala.collection.mutable.ListBuffer
*
* @author Jens Halm
*/
object BlockParsers {
private[laika] object BlockParsers {

val ws: Characters[String] = anyOf(
' '
) // other whitespace has been replaced with spaces by preprocessor
// other whitespace has been replaced with spaces by preprocessor
val ws: Characters[String] = anyOf(' ')

/** Parses a transition (rule).
*
Expand All @@ -62,8 +61,9 @@ object BlockParsers {
(punctuationChar.min(4) ~ wsEol ~ lookAhead(blankLine)).as(Rule())
}

/** Parses a single paragraph. Everything between two blank lines that is not
* recognized as a special reStructuredText block type will be parsed as a regular paragraph.
/** Parses a single paragraph.
* Everything between two blank lines that is not recognized
* as a special reStructuredText block type will be parsed as a regular paragraph.
*/
lazy val paragraph: BlockParserBuilder = BlockParserBuilder.recursive { recParsers =>
val interruptions = recParsers.paragraphInterruptions()
Expand All @@ -85,7 +85,7 @@ object BlockParsers {

/** Parses a section header with both overline and underline.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections]].
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections]].
*/
lazy val headerWithOverline: BlockParserBuilder = BlockParserBuilder.withSpans { spanParsers =>
val spanParser = punctuationChar.take(1) >> { start =>
Expand All @@ -107,7 +107,7 @@ object BlockParsers {

/** Parses a section header with an underline, but no overline.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections]].
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections]].
*/
lazy val headerWithUnderline: BlockParserBuilder = BlockParserBuilder.withSpans { spanParsers =>
val spanParser = nextNot(' ') ~ not(eof) ~> restOfLine.trim.line >> { title =>
Expand All @@ -127,11 +127,9 @@ object BlockParsers {
}
}

/** Parses a doctest block. This is a feature which is very specific to the
* world of Python where reStructuredText originates. Therefore the resulting
* `DoctestBlock` tree element is not part of the standard Laika AST model.
* When this block type is used the corresponding special renderers must
* be enabled (e.g. the `ExtendedHTMLRenderer` renderer for HTML).
/** Parses a doctest block.
* This is a feature which is very specific to the world of Python where reStructuredText originates.
* Therefore the resulting `DoctestBlock` tree element is not part of the standard Laika AST model.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#doctest-blocks]]
*/
Expand All @@ -142,7 +140,7 @@ object BlockParsers {

/** Parses a block quote with an optional attribution.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#block-quotes]]
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#block-quotes]]
*/
lazy val blockQuote: BlockParserBuilder = BlockParserBuilder.recursive { recParsers =>
val attributionStart = "---" | "--" | "\u2014" // em dash
Expand All @@ -161,9 +159,9 @@ object BlockParsers {
}

/** Parses a literal block, either quoted or indented.
* Only used when the preceding block ends with a double colon (`::`).
* Only used when the preceding block ends with a double colon (`::`).
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#literal-blocks]]
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#literal-blocks]]
*/
val literalBlock: Parser[Block] = {
val indented = indentedBlock(firstLineIndented = true).map(src => LiteralBlock(src.input))
Expand All @@ -175,17 +173,17 @@ object BlockParsers {
indented | quoted
}

/** Builds a parser for a list of blocks based on the parser for a single block.
/** Builds a parser for a list of blocks based on the parser for a single block.
*
* Adds the processing required for cases where a block has influence
* on the parsing or processing of the subsequent block.
* Adds the processing required for cases where a block has influence
* on the parsing or processing of the subsequent block.
*
* This includes checking each Paragraph for a double colon ending which turns
* the following block into a literal block as well as processing internal
* link targets and section headers.
* This includes checking each Paragraph for a double colon ending which turns
* the following block into a literal block as well as processing internal
* link targets and section headers.
*
* @param blockParser the parser for a single block element
* @return a parser for a list of blocks
* @param blockParser the parser for a single block element
* @return a parser for a list of blocks
*/
def createBlockListParser(blockParser: Parser[Block]): Parser[Seq[Block]] = Parser { in =>
val defaultBlock = blockParser <~ opt(blankLines)
Expand Down
18 changes: 9 additions & 9 deletions core/shared/src/main/scala/laika/rst/ExplicitBlockParsers.scala
Original file line number Diff line number Diff line change
Expand Up @@ -32,23 +32,23 @@ import laika.parse.text.PrefixedParser
*
* @author Jens Halm
*/
class ExplicitBlockParsers(recParsers: RecursiveParsers) {
private[laika] class ExplicitBlockParsers(recParsers: RecursiveParsers) {

import recParsers._

private val explicitStart = ".." ~ ws.min(1)

/** Parses all types of explicit block items.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#explicit-markup-blocks]].
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#explicit-markup-blocks]].
*/
lazy val explicitBlockItem: PrefixedParser[Block] =
(explicitStart ~> (footnote | citation | linkTarget | comment)) |
(".." ~ nextIn('\n') ~> comment)

/** Parses a footnote.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#footnotes]].
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#footnotes]].
*/
lazy val footnote: Parser[FootnoteDefinition] = {

Expand Down Expand Up @@ -78,7 +78,7 @@ class ExplicitBlockParsers(recParsers: RecursiveParsers) {

/** Parses a citation.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#citations]].
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#citations]].
*/
lazy val citation: Parser[Citation] = {
val prefix = "[" ~> simpleRefName <~ "]" ~ ws
Expand All @@ -88,7 +88,7 @@ class ExplicitBlockParsers(recParsers: RecursiveParsers) {

/** Parses a link definition, either an internal, external or indirect link.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#hyperlink-targets]].
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#hyperlink-targets]].
*/
lazy val linkTarget: Parser[Block with Span] = {

Expand Down Expand Up @@ -119,7 +119,7 @@ class ExplicitBlockParsers(recParsers: RecursiveParsers) {

/** Parses a comment.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#comments]].
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#comments]].
*/
val comment: Parser[Comment] = indentedBlock().map(src => Comment(src.input.trim))

Expand Down Expand Up @@ -148,10 +148,10 @@ object ExplicitBlockParsers {
}
}

/** Parses the short variant of an anonymous link definition
* (that starts with `__` instead of `.. __:`)
/** Parses the short variant of an anonymous link definition
* (that starts with `__` instead of `.. __:`)
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#anonymous-hyperlinks]].
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#anonymous-hyperlinks]].
*/
lazy val shortAnonymousLinkTarget: BlockParserBuilder = BlockParserBuilder.standalone {
"__ " ~> linkDefinitionBody.map(LinkDefinition.create("", _))
Expand Down
12 changes: 6 additions & 6 deletions core/shared/src/main/scala/laika/rst/InlineParsers.scala
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ import laika.rst.ast.{ InterpretedText, ReferenceName, RstStyle, SubstitutionRef
*
* @author Jens Halm
*/
object InlineParsers {
private[laika] object InlineParsers {

/** Parses an escaped character. For most characters it produces the character
* itself as the result with the only exception being an escaped space character
Expand Down Expand Up @@ -258,15 +258,15 @@ object InlineParsers {

/** Parses a span of emphasized text.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#emphasis]]
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#emphasis]]
*/
lazy val em: SpanParserBuilder = SpanParserBuilder.recursive { implicit recParsers =>
span(delimiter('*').prevNot('*'), delimiter("*").nextNot('*')).map(Emphasized(_))
}.withLowPrecedence

/** Parses a span of text with strong emphasis.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#strong-emphasis]]
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#strong-emphasis]]
*/
lazy val strong: SpanParserBuilder = SpanParserBuilder.recursive { implicit recParsers =>
val delim = literal("**")
Expand All @@ -282,7 +282,7 @@ object InlineParsers {

/** Parses an inline literal element.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-literals]].
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-literals]].
*/
lazy val inlineLiteral: SpanParserBuilder = SpanParserBuilder.standalone {
markupStart("``", "``") ~> delimitedBy(markupEnd("``")).map(Literal(_))
Expand Down Expand Up @@ -426,13 +426,13 @@ object InlineParsers {

/** Parses a standalone HTTP or HTTPS hyperlink (with no surrounding markup).
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#standalone-hyperlinks]]
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#standalone-hyperlinks]]
*/
lazy val uri: SpanParserBuilder = autoLinks.http

/** Parses a standalone email address (with no surrounding markup).
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#standalone-hyperlinks]]
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#standalone-hyperlinks]]
*/
lazy val email: SpanParserBuilder = autoLinks.email

Expand Down
14 changes: 7 additions & 7 deletions core/shared/src/main/scala/laika/rst/ListParsers.scala
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ import scala.collection.mutable.ListBuffer
*
* @author Jens Halm
*/
object ListParsers {
private[laika] object ListParsers {

private def listItem[I <: ListItem](itemStart: Parser[String], newListItem: Seq[Block] => I)(
implicit recParsers: RecursiveParsers
Expand Down Expand Up @@ -94,7 +94,7 @@ object ListParsers {

/** Parses a bullet list with any of the supported bullet characters.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-lists]].
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-lists]].
*/
lazy val bulletList: BlockParserBuilder = BlockParserBuilder.recursive { implicit recParsers =>
lookAhead(bulletListStart <~ ws.min(1)) >> { symbol =>
Expand Down Expand Up @@ -141,7 +141,7 @@ object ListParsers {

/** Parses an enumerated list in any of the supported combinations of enumeration style and formatting.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#enumerated-lists]].
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#enumerated-lists]].
*/
lazy val enumList: BlockParserBuilder = BlockParserBuilder.recursive { implicit recParsers =>
import EnumType._
Expand Down Expand Up @@ -184,7 +184,7 @@ object ListParsers {

/** Parses a definition list.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#definition-lists]].
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#definition-lists]].
*/
lazy val definitionList: BlockParserBuilder = BlockParserBuilder.recursive { recParsers =>
val tableStart = anyOf(' ', '=') ~ eol
Expand Down Expand Up @@ -212,7 +212,7 @@ object ListParsers {

/** Parses a field list.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#field-lists]].
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#field-lists]].
*/
lazy val fieldList: BlockParserBuilder = BlockParserBuilder.recursive { recParsers =>
val nameParser = ":" ~> recParsers.escapedUntil(':').line <~ (lookAhead(eol).as("") | " ")
Expand All @@ -227,7 +227,7 @@ object ListParsers {

/** Parses an option list.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#option-lists]].
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#option-lists]].
*/
lazy val optionList: BlockParserBuilder = BlockParserBuilder.recursive { recParsers =>
val optionString = someOf(CharGroup.alphaNum.add('_').add('-'))
Expand Down Expand Up @@ -259,7 +259,7 @@ object ListParsers {

/** Parses a block of lines with line breaks preserved.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#line-blocks]].
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#line-blocks]].
*/
lazy val lineBlock: BlockParserBuilder = BlockParserBuilder.recursive { recParsers =>
val itemStart = oneOf('|')
Expand Down
14 changes: 7 additions & 7 deletions core/shared/src/main/scala/laika/rst/TableParsers.scala
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ import scala.collection.mutable.ListBuffer
*
* @author Jens Halm
*/
object TableParsers {
private[laika] object TableParsers {

private abstract class TableElement

Expand Down Expand Up @@ -62,8 +62,8 @@ object TableParsers {
private var currentLine: Option[LineSource] = None
private def allLines: mutable.Buffer[LineSource] = previousLines ++ currentLine.toBuffer

var rowSpan = 1
var colSpan = 1
private var rowSpan = 1
private var colSpan = 1

var removed: Boolean = false

Expand Down Expand Up @@ -92,7 +92,7 @@ object TableParsers {
}

@nowarn("cat=deprecation")
def trimmedCellContent: Option[BlockSource] = {
private def trimmedCellContent: Option[BlockSource] = {
NonEmptyChain.fromSeq(allLines.toSeq).map { nonEmptyLines =>
val minIndent = nonEmptyLines.map { line =>
if (line.input.trim.isEmpty) Int.MaxValue
Expand All @@ -109,7 +109,7 @@ object TableParsers {
}
}

def parsedCellContent: Seq[Block] = trimmedCellContent.fold[Seq[Block]](Nil)(src =>
private def parsedCellContent: Seq[Block] = trimmedCellContent.fold[Seq[Block]](Nil)(src =>
recParser.recursiveBlocks.parse(src).getOrElse(Nil)
)

Expand Down Expand Up @@ -214,7 +214,7 @@ object TableParsers {

/** Parses a grid table.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables]].
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables]].
*/
lazy val gridTable: BlockParserBuilder = BlockParserBuilder.recursive { recParsers =>
val intersectChar = '+'
Expand Down Expand Up @@ -309,7 +309,7 @@ object TableParsers {

/** Parses a simple table.
*
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#simple-tables]].
* See [[http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#simple-tables]].
*/
lazy val simpleTable: BlockParserBuilder = BlockParserBuilder.recursive { recParsers =>
val intersect = someOf(' ').count
Expand Down
5 changes: 3 additions & 2 deletions core/shared/src/main/scala/laika/rst/ast/RstStyle.scala
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,12 @@ package laika.rst.ast

import laika.ast.{ Options, Styles }

/** Constants for style names wrapped in Options instances which are commonly used by Laika's reStructuredText parsers and rewrite rules.
/** Constants for style names wrapped in Options instances
* which are commonly used by Laika's reStructuredText parsers and rewrite rules.
*
* @author Jens Halm
*/
object RstStyle {
private[rst] object RstStyle {

val line: Options = Styles("line")
val lineBlock: Options = Styles("line-block")
Expand Down
Loading

0 comments on commit 49c9e70

Please sign in to comment.