wip: tutorial.md

Author: bishabosha

docs/generateDocs.mill

@@ -5,6 +5,7 @@ def generateTutorial(sourcePath: os.Path, destPath: os.Path) =  {
   var isDocs = Option.empty[Int]
   var isCode = false
   val outputLines = collection.mutable.Buffer.empty[String]
+  val snippets = collection.mutable.HashMap.empty[String, scala.collection.BufferedIterator[String]]
   outputLines.append(generatedCodeHeader)
   for (line <- os.read.lines(sourcePath)) {
     val isDocsIndex = line.indexOf("// +DOCS")
@@ -25,6 +26,24 @@ def generateTutorial(sourcePath: os.Path, destPath: os.Path) =  {
       (suffix, isCode) match{
         case ("", _) => outputLines.append("")
 
+        case (s"// +INCLUDE SNIPPET [$key] $rest", _) =>
+          // reuse the iterator each time,
+          // basically assume snippets are requested in order.
+          val sublines: scala.collection.BufferedIterator[String] = snippets.getOrElseUpdate(rest, os.read.lines(mill.api.WorkspaceRoot.workspaceRoot / os.SubPath(rest)).iterator.buffered)
+          val start = s"// +SNIPPET [$key]"
+          val end = s"// -SNIPPET [$key]"
+          while (sublines.hasNext && !sublines.head.contains(start)) {
+            sublines.next() // drop lines until we find the start
+          }
+          val indent = sublines.headOption.map(_.indexOf(start)).getOrElse(-1)
+          if (indent != -1) {
+            sublines.next() // skip the start line
+            while (sublines.hasNext && !sublines.head.contains(end)) {
+              outputLines.append(sublines.next().drop(indent))
+            }
+          } else {
+            outputLines.append("")
+          }
         case (s"// +INCLUDE $rest", _) =>
           os.read.lines(mill.api.WorkspaceRoot.workspaceRoot / os.SubPath(rest)).foreach(outputLines.append)
 
@@ -124,6 +143,10 @@ def generateReference(dest: os.Path, scalafmtCallback: (Seq[os.Path], os.Path) =
        |databases, due to differences in how each database parses SQL. These differences
        |are typically minor, and as long as you use the right `Dialect` for your database
        |ScalaSql should do the right thing for you.
+       |
+       |>**A note for users of `SimpleTable`**: The examples in this document assume usage of
+       |>`Table`, with a higher kinded type parameter on a case class. If you are using
+       |>`SimpleTable`, then the same code snippets should work by dropping `[Sc]`.
        |""".stripMargin
   )
   val recordsWithoutDuplicateSuites = records

docs/reference.md

@@ -16,6 +16,10 @@ databases, due to differences in how each database parses SQL. These differences
 are typically minor, and as long as you use the right `Dialect` for your database
 ScalaSql should do the right thing for you.
 
+>**A note for users of `SimpleTable`**: The examples in this document assume usage of
+>`Table`, with a higher kinded type parameter on a case class. If you are using
+>`SimpleTable`, then the same code snippets should work by dropping `[Sc]`.
+
 ## DbApi
 Basic usage of `db.*` operations such as `db.run`
 ### DbApi.renderSql

docs/tutorial.md

@@ -1,7 +1,7 @@
 [//]: # (GENERATED SOURCES, DO NOT EDIT DIRECTLY)
 
 
-This tutorials is a tour of how to use ScalaSql, from the most basic concepts
+This tutorial is a tour of how to use ScalaSql, from the most basic concepts
 to writing some realistic queries. If you are browsing this on Github, you
 can open the `Outline` pane on the right to browse the section headers to
 see what we will cover and find anything specific of interest to you.
@@ -71,8 +71,14 @@ supported databases, to see what kind of set up is necessary for each one
 ### Modeling Your Schema
 
 Next, you need to define your data model classes. In ScalaSql, your data model
-is defined using `case class`es with each field wrapped in the wrapper type
-parameter `T[_]`. This allows us to re-use the same case class to represent
+is defined using `case class`es with each field representing a column in an database table.
+
+There are two flavors to consider: `Table` (available for Scala 2.13+), and `SimpleTable` (Scala 3.7+).
+
+**Using `Table`**
+
+Declare your case class with a type parameter `T[_]`, which is used to wrap the type of each
+field. This allows us to re-use the same case class to represent
 both database values (when `T` is `scalasql.Expr`) as well as Scala values
 (when `T` is `scalasql.Sc`).
 
@@ -120,6 +126,59 @@ case class CountryLanguage[T[_]](
 object CountryLanguage extends Table[CountryLanguage]()
 ```
 
+**Using `SimpleTable`**
+> Note: only available in the `com.lihaoyi::scalasql-namedtuples` library, which supports Scala 3.7.0+
+
+Declare your case class as usual. Inside of queries, the class will be represented by a `Record` with the same fields, but wrapped in `scalasql.Expr`.
+
+Here, we define three classes `Country` `City` and `CountryLanguage`, modeling
+the database tables we saw above.
+
+Also included is the necessary import statement to include the `SimpleTable` definition.
+
+```scala
+import scalasql.simple.{*, given}
+
+case class Country(
+    code: String,
+    name: String,
+    continent: String,
+    region: String,
+    surfaceArea: Int,
+    indepYear: Option[Int],
+    population: Long,
+    lifeExpectancy: Option[Double],
+    gnp: Option[scala.math.BigDecimal],
+    gnpOld: Option[scala.math.BigDecimal],
+    localName: String,
+    governmentForm: String,
+    headOfState: Option[String],
+    capital: Option[Int],
+    code2: String
+)
+
+object Country extends SimpleTable[Country]
+
+case class City(
+    id: Int,
+    name: String,
+    countryCode: String,
+    district: String,
+    population: Long
+)
+
+object City extends SimpleTable[City]
+
+case class CountryLanguage(
+    countryCode: String,
+    language: String,
+    isOfficial: Boolean,
+    percentage: Double
+)
+
+object CountryLanguage extends SimpleTable[CountryLanguage]
+```
+
 ### Creating Your Database Client
 Lastly, we need to initialize our `scalasql.DbClient`. This requires
 passing in a `java.sql.Connection`, a `scalasql.Config` object, and the SQL dialect
@@ -201,11 +260,16 @@ db.run(query).take(3) ==> Seq(
 )
 
 ```
-Notice that `db.run` returns instances of type `City[Sc]`. `Sc` is `scalasql.Sc`,
+Notice that `db.run` returns instances of type `City[Sc]` (or `City` if using `SimpleTable`).
+
+`Sc` is `scalasql.Sc`,
 short for the "Scala" type, representing a `City` object containing normal Scala
 values. The `[Sc]` type parameter must be provided explicitly whenever creating,
 type-annotating, or otherwise working with these `City` values.
 
+> In this tutorial, unless otherwise specified, we will assume usage of the `Table` encoding.
+> If you are using `SimpleTable`, the same code will work, but drop `[Sc]` type arguments.
+
 In this example, we do `.take(3)` after running the query to show only the first
 3 table entries for brevity, but by that point the `City.select` query had already
 fetched the entire database table into memory. This can be a problem with non-trivial
@@ -235,8 +299,12 @@ db.run(query) ==> City[Sc](3208, "Singapore", "SGP", district = "", population =
 ```
 Note that we use `===` rather than `==` for the equality comparison. The
 function literal passed to `.filter` is given a `City[Expr]` as its parameter,
-representing a `City` that is part of the database query, in contrast to the
-`City[Sc]`s that `db.run` returns , and so `_.name` is of type `Expr[String]`
+(or `Record[City, Expr]` with the `SimpleTable` encoding) representing a `City`
+that is part of the database query, in contrast to the
+`City[Sc]`s that `db.run` returns.
+
+Within a query therefore `_.name` is a field selection on the function parameter,
+resulting in `Expr[String]`,
 rather than just `String` or `Sc[String]`. You can use your IDE's
 auto-complete to see what operations are available on `Expr[String]`: typically
 they will represent SQL string functions rather than Scala string functions and
@@ -309,7 +377,8 @@ db.run(query).take(2) ==> Seq(
 )
 
 ```
-Again, all the operations within the query work on `Expr`s: `c` is a `City[Expr]`,
+Again, all the operations within the query work on `Expr`s:
+`c` is a `City[Expr]` (or `Record[City, Expr]` for `SimpleTable`),
 `c.population` is an `Expr[Int]`, `c.countryCode` is an `Expr[String]`, and
 `===` and `>` and `&&` on `Expr`s all return `Expr[Boolean]`s that represent
 a SQL expression that can be sent to the Database as part of your query.
@@ -427,8 +496,61 @@ db.run(query) ==>
     "SINGAPORE",
     4 // population in millions
   )
+
 ```
 
+**Mapping with named tuples**
+> Note: only available in the `com.lihaoyi::scalasql-namedtuples` library, which supports Scala 3.7.0+
+
+You can also use named tuples to map the results of a query.
+```scala
+import scalasql.namedtuples.NamedTupleQueryable.given
+
+val query = Country.select.map(c =>
+  (name = c.name, continent = c.continent)
+)
+
+db.run(query).take(5) ==> Seq(
+  (name = "Afghanistan", continent = "Asia"),
+  (name = "Netherlands", continent = "Europe"),
+  (name = "Netherlands Antilles", continent = "North America"),
+  (name = "Albania", continent = "Europe"),
+  (name = "Algeria", continent = "Africa")
+)
+```
+
+**Updating `Record` fields**
+> Note: only relevant when using the `SimpleTable` encoding.
+
+When using `SimpleTable`, within the `.map` query `c` is of type
+`Record[Country, Expr]`. Records are converted back to their associated case class
+(e.g. `Country`) with `db.run`.
+
+If you want to apply updates to any of the fields before returning, the `Record` class
+provides an `updates` method. This lets you provide an arbitrary sequence of updates to
+apply in-order to the record. You can either provide a value with `:=`,
+or provide a function that transforms the old value. For example:
+
+```scala
+val query = Country.select.map(c =>
+  c.updates(
+    _.population := 0L,
+    _.name(old => Expr("🌐 ") + old)
+  )
+)
+
+db.run(query).take(5).match {
+  case Seq(
+    Country(name = "🌐 Afghanistan", population = 0L),
+    Country(name = "🌐 Netherlands", population = 0L),
+    Country(name = "🌐 Netherlands Antilles", population = 0L),
+    Country(name = "🌐 Albania", population = 0L),
+    Country(name = "🌐 Algeria", population = 0L)
+  ) =>
+} ==> ()
+```
+
+
 ### Aggregates
 
 You can perform simple aggregates like `.sum` as below, where we
@@ -1361,6 +1483,23 @@ db.run(
 
 db.run(City.select.filter(_.id === 313373).single) ==>
   City[Sc](CityId(313373), "test", "XYZ", "district", 1000000)
+
+
+```
+You can also use `TypeMapper#bimap` for the common case where you want the
+new `TypeMapper` to behave the same as an existing `TypeMapper`, just with
+conversion functions to convert back and forth between the old type and new type:
+
+```scala
+case class CityId2(value: Int)
+
+object CityId2 {
+  implicit def tm: TypeMapper[CityId2] = TypeMapper[Int].bimap[CityId2](
+    city => city.value,
+    int => CityId2(int)
+  )
+}
+
 ```
 
 ```scala
@@ -1387,8 +1526,7 @@ db.run(
 
 db.run(City2.select.filter(_.id === 31337).single) ==>
   City2[Sc](CityId2(31337), "test", "XYZ", "district", 1000000)
-
-st("customTableColumnNames") {
+```
 
 ## Customizing Table and Column Names
 

readme.md

@@ -56,12 +56,12 @@ dbClient.transaction{ db =>
 }
 ```
 
-ScalaSql supports database connections to PostgreSQL, MySQL, Sqlite, and H2 databases. 
+ScalaSql supports database connections to PostgreSQL, MySQL, Sqlite, and H2 databases.
 Support for additional databases can be easily added.
 
 ScalaSql is a relatively new library, so please try it out, but be aware you may hit bugs
 or missing features! Please open [Discussions](https://github.com/com-lihaoyi/scalasql/discussions)
-for any questions, file [Issues](https://github.com/com-lihaoyi/scalasql/issues) for any 
+for any questions, file [Issues](https://github.com/com-lihaoyi/scalasql/issues) for any
 bugs you hit, or send [Pull Requests](https://github.com/com-lihaoyi/scalasql/pulls) if
 you are able to investigate and fix them!
 
@@ -76,10 +76,56 @@ ivy"com.lihaoyi::scalasql:0.1.19"
 
 ScalaSql supports Scala 2.13.x and >=3.6.2
 
+### SimpleTable variant based on named tuples
+
+For Scala versions >=3.7.0 supporting named tuples, an alternative way to define tables is supported.
+
+Add the following to your `build.sc` file as follows:
+
+<!-- TODO: scalasql-simple? -->
+```scala
+ivy"com.lihaoyi::scalasql-namedtuples:0.1.19"
+```
+
+And taking the example above, the only thing that needs to change is the following:
+```diff
+-import scalasql._, SqliteDialect._
++import scalasql.simple._, SqliteDialect._
+
+ // Define your table model classes
+-case class City[T[_]](
+-    id: T[Int],
+-    name: T[String],
+-    countryCode: T[String],
+-    district: T[String],
+-    population: T[Long]
+-)
+-object City extends Table[City]
++case class City(
++    id: Int,
++    name: String,
++    countryCode: String,
++    district: String,
++    population: Long
++)
++object City extends SimpleTable[City]
+```
+
+And you now have the option to return named tuples from queries:
+```diff
+ val fewLargestCities = db.run(
+    City.select
+        .sortBy(_.population).desc
+        .drop(5).take(3)
+-       .map(c => (c.name, c.population))
++       .map(c => (name = c.name, pop = c.population))
+  )
+```
+
 ## Documentation
 
 * ScalaSql Quickstart Examples: self-contained files showing how to set up ScalaSql to
-  connect your Scala code to a variety of supported databases and perform simple DDL and 
+  connect your Scala code to a variety of supported databases and perform simple DDL and
   `SELECT`/`INSERT`/`UPDATE`/`DELETE` operations:
     * [Postgres](scalasql/test/src/example/PostgresExample.scala)
     * [MySql](scalasql/test/src/example/MySqlExample.scala)
@@ -104,7 +150,7 @@ ScalaSql supports Scala 2.13.x and >=3.6.2
     to execute queries
   * [Transaction](docs/reference.md#transaction), covering usage of transactions
     and savepoints
-  * [Select](docs/reference.md#select), [Insert](docs/reference.md#insert), 
+  * [Select](docs/reference.md#select), [Insert](docs/reference.md#insert),
     [Update](docs/reference.md#update), [Delete](docs/reference.md#delete):
     covering operations on the primary queries you are likely to use
   * [Join](docs/reference.md#join), covering different kinds of joins
@@ -113,14 +159,14 @@ ScalaSql supports Scala 2.13.x and >=3.6.2
   * [Expression Operations](docs/reference.md#exprops), covering the different
     types of `Expr[T]` values and the different operations you can do on each one
   * [Option Operations](docs/reference.md#optional), operations on `Expr[Option[T]`
-  * [Window Functions](docs/reference.md#windowfunctions), 
+  * [Window Functions](docs/reference.md#windowfunctions),
     [With-Clauses/Common-Table-Expressions](docs/reference.md#withcte)
   * [Postgres](docs/reference.md#postgresdialect), [MySql](docs/reference.md#mysqldialect),
     [Sqlite](docs/reference.md#sqlitedialect), [H2](docs/reference.md#h2dialect) Dialects:
     operations that are specific to each database that may not be generally applicable
 
 * [ScalaSql Design](docs/design.md): discusses the design of the ScalaSql library, why it
-  is built the way it is, what tradeoffs it makes, and how it compares to other 
+  is built the way it is, what tradeoffs it makes, and how it compares to other
   common Scala database query libraries. Ideal for contributors who want to understand
   the structure of the ScalaSql codebase, or for advanced users who may need to
   understand enough to extend ScalaSql with custom functionality.