From 6c6a0117757e606034319c6a73b03d1022a06552 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bart=C5=82omiej=20Kozak?= Date: Wed, 12 Jun 2024 17:19:19 +0200 Subject: [PATCH] add Readme --- .idea/misc.xml | 2 +- README.md | 90 +++++++++++++++++ src/test/scala/integration/Readme.scala | 128 ++++++++++++++++++++++++ 3 files changed, 219 insertions(+), 1 deletion(-) create mode 100644 README.md create mode 100644 src/test/scala/integration/Readme.scala diff --git a/.idea/misc.xml b/.idea/misc.xml index 69ace3f..07115cd 100644 --- a/.idea/misc.xml +++ b/.idea/misc.xml @@ -1,6 +1,6 @@ - + \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..c4249a6 --- /dev/null +++ b/README.md @@ -0,0 +1,90 @@ + + +# Smark + + +Smark is a markdown generation library in typesafe way + +dupa + +Do not take this project seriously, first of all I wanted to learn some mechanisms from Scala 3 + +## Usage + + +Add the following to your build.sbt: + +```scala +libraryDependencies += "halotukozak" %% "smark" % "0.1.0-SNAPSHOT" +``` + +Then you can use Smark in your Scala 3 project: + +```scala +import halotukozak.smark.typography.* + +markdown { +heading[1]("Smark") + paragraph { + text[Normal]("Smark is a markdown generation library in typesafe way") + quote[Important]("Do not take this project seriously, first of all I wanted to learn some mechanisms from Scala 3") + } +} +``` + +will generate: + +``` +# Smark + + +Smark is a markdown generation library in typesafe way + +> [!Important] +> Do not take this project seriously, first of all I wanted to learn some mechanisms from Scala 3 +``` + +If you prefer to skip brackets, you can use the following syntax: + +```scala +import halotukozak.smark.typography.* + +markdown: + heading[1]("Smark") + paragraph: + text[Normal]("Smark is a markdown generation library in typesafe way") + quote[Important]("Do not take this project seriously, first of all I wanted to learn some mechanisms from Scala 3") + +``` + +## Main Scala features used in Smark + +### Context Functions + + +```scala +def table(init: Table ?=> MdUnit)(using m: MdElement): MdUnit +``` + +takes a parameter which operates on the Table instance what enables a syntax like this: + +```scala + + |table { + | header("column1", "column2") + | row { + | cell("row1column1") + | cell("row1column2") + | } + | row { + | cell("row2column1") + | cell("row2column2") + | } + |} + | +``` + +### Implicit Conversions + + +[Implicit conversions](https://docs.scala-lang.org/scala3/book/ca-implicit-conversions.html) \ No newline at end of file diff --git a/src/test/scala/integration/Readme.scala b/src/test/scala/integration/Readme.scala new file mode 100644 index 0000000..13c1876 --- /dev/null +++ b/src/test/scala/integration/Readme.scala @@ -0,0 +1,128 @@ +package halotukozak.smark +package integration + +import typography.* + +import _root_.java.io.FileWriter +import halotukozak.smark.given_Conversion_String_MdUnit + + +@main +def generateReadme(): Unit = + val file = new FileWriter("README.md") + try file.write(content) + finally file.close() + +//noinspection ScalaUnusedExpression +val content: String = + markdown { + comment("Do not edit this file manually, it is generated by Smark") + heading[1]("Smark") + paragraph { + "Smark is a markdown generation library in typesafe way": MdUnit + "Do not take this project seriously, first of all I wanted to learn some mechanisms from Scala 3" + } + heading[2]("Usage") + paragraph { + "Add the following to your build.sbt:": MdUnit + code { + scala"""libraryDependencies += "halotukozak" %% "smark" % "0.1.0-SNAPSHOT"""" + } + "Then you can use Smark in your Scala 3 project:": MdUnit + code { + scala"""|import halotukozak.smark.typography.* + | + |markdown { + |heading[1]("Smark") + | paragraph { + | text[Normal]("Smark is a markdown generation library in typesafe way") + | quote[Important]("Do not take this project seriously, first of all I wanted to learn some mechanisms from Scala 3") + | } + |}""".stripMargin + } + "will generate:": MdUnit + text[BlockCode] { + markdown { + heading[1]("Smark") + paragraph { + text[Normal]("Smark is a markdown generation library in typesafe way") + quote[Important]("Do not take this project seriously, first of all I wanted to learn some mechanisms from Scala 3") + } + } + } + } + "If you prefer to skip brackets, you can use the following syntax:": MdUnit + code { + scala"""|import halotukozak.smark.typography.* + | + |markdown: + | heading[1]("Smark") + | paragraph: + | text[Normal]("Smark is a markdown generation library in typesafe way") + | quote[Important]("Do not take this project seriously, first of all I wanted to learn some mechanisms from Scala 3") + |""".stripMargin + } + heading[2]("Main Scala features used in Smark") + heading[3]("Context Functions") + paragraph { + string.link["Context functions"]("https://docs.scala-lang.org/scala3/reference/contextual/context-functions.html") + " are used to create a DSL. For example table function:" + code { + scala"def table(init: Table ?=> MdUnit)(using m: MdElement): MdUnit".stripMargin + } + "takes a parameter which operates on the Table instance what enables a syntax like this:": MdUnit + code { + scala"""| + |table { + | header("column1", "column2") + | row { + | cell("row1column1") + | cell("row1column2") + | } + | row { + | cell("row2column1") + | cell("row2column2") + | } + |} + |""" + } + } + heading[3]("Implicit Conversions") + paragraph { + string.link["Implicit conversions"]("https://docs.scala-lang.org/scala3/book/ca-implicit-conversions.html") + " are used in two places:": MdUnit + list[Asterisk]( + "Converting String to MdUnit", + "Converting String to Column" + ) + heading[4]("Converting String to MdUnit") + paragraph { + "Implicit conversion is defined in the companion object of MdElement:": MdUnit + code { + scala"""given Conversion[String, MdUnit] = MdElement.fromString""" + } + "This allows to use String in the context of MdUnit. For example:": MdUnit + code { + scala"""|paragraph { + | "This is a paragraph" + |}""".stripMargin + } + "also allows to use raw String in place of `text[Normal]": MdUnit + code { + scala"""|//noinspection ScalaUnusedExpression + |paragraph { + | "Conversion to MdUnit" : MdUnit + | "Last expression do not have to be converted" + |}""".stripMargin + } + "as you can see, the `//noinspection ScalaUnusedExpression` is needed to suppress the warning about unused expression for IntelliJ IDEA" + } + heading[4]("Converting String to Column") + paragraph { + "Implicit conversion enables syntax like this:": MdUnit + code { + scala"""header("column1", "column2" : Left)""" + } + "what make the second column left aligned" + } + } + } +