Primary read/write functions for JSON and binary formats, providing the main entry points for uPickle serialization with configuration options for formatting and behavior.
Reads JSON input into Scala values with optional trace support for debugging.
/**
* Reads the given JSON input into a Scala value
* @param s JSON input (string, InputStream, etc.)
* @param trace Enable tracing for debugging serialization issues
* @return Deserialized Scala value of type T
*/
def read[T: Reader](s: ujson.Readable, trace: Boolean = false): TUsage Examples:
import upickle.default._
// From string
val person = read[Person]("""{"name":"Alice","age":30}""")
// From file
val data = read[List[Int]](os.read(os.pwd / "data.json"))
// With tracing
val traced = read[Person](json, trace = true)Writes Scala values as JSON strings with formatting options.
/**
* Write the given Scala value as a JSON string
* @param t Value to serialize
* @param indent Indentation level (-1 for compact, >=0 for pretty printing)
* @param escapeUnicode Whether to escape unicode characters
* @param sortKeys Whether to sort object keys alphabetically
* @return JSON string representation
*/
def write[T: Writer](t: T, indent: Int = -1, escapeUnicode: Boolean = false, sortKeys: Boolean = false): StringUsage Examples:
import upickle.default._
val person = Person("Alice", 30)
// Compact JSON
val compact = write(person)
// Result: {"name":"Alice","age":30}
// Pretty-printed JSON
val pretty = write(person, indent = 2)
// Result:
// {
// "name": "Alice",
// "age": 30
// }
// Sorted keys
val sorted = write(person, sortKeys = true)Reads MessagePack binary input into Scala values.
/**
* Reads the given MessagePack input into a Scala value
* @param s MessagePack binary input
* @param trace Enable tracing for debugging
* @return Deserialized Scala value of type T
*/
def readBinary[T: Reader](s: upack.Readable, trace: Boolean = false): TUsage Examples:
import upickle.default._
// From byte array
val binary: Array[Byte] = getBinaryData()
val person = readBinary[Person](binary)
// From InputStream
val stream: InputStream = getInputStream()
val data = readBinary[List[Int]](stream)Writes Scala values as MessagePack binary data.
/**
* Write the given Scala value as a MessagePack binary
* @param t Value to serialize
* @param sortKeys Whether to sort object keys alphabetically
* @return MessagePack byte array
*/
def writeBinary[T: Writer](t: T, sortKeys: Boolean = false): Array[Byte]Usage Examples:
import upickle.default._
val person = Person("Alice", 30)
// Binary serialization
val binary = writeBinary(person)
// With sorted keys
val sortedBinary = writeBinary(person, sortKeys = true)
// Write to file
os.write(os.pwd / "data.msgpack", binary)Writes Scala values directly to JSON and MessagePack AST types.
/**
* Write the given Scala value as a JSON struct
* @param t Value to serialize
* @return ujson.Value representation
*/
def writeJs[T: Writer](t: T): ujson.Value
/**
* Write the given Scala value as a MessagePack struct
* @param t Value to serialize
* @return upack.Msg representation
*/
def writeMsg[T: Writer](t: T): upack.MsgUsage Examples:
import upickle.default._
val person = Person("Alice", 30)
// JSON AST
val jsonAst = writeJs(person)
// Result: ujson.Obj("name" -> ujson.Str("Alice"), "age" -> ujson.Num(30))
// MessagePack AST
val msgAst = writeMsg(person)
// Result: upack.Obj("name" -> upack.Str("Alice"), "age" -> upack.Int32(30))Direct access to Reader, Writer, and ReadWriter instances.
/**
* Gets the Reader typeclass instance for type T
*/
def reader[T: Reader]: Reader[T]
/**
* Gets the Writer typeclass instance for type T
*/
def writer[T: Writer]: Writer[T]
/**
* Gets the ReadWriter typeclass instance for type T
*/
def readwriter[T: ReadWriter]: ReadWriter[T]Usage Examples:
import upickle.default._
// Get type class instances
val personReader = reader[Person]
val personWriter = writer[Person]
val personRW = readwriter[Person]
// Use directly
val person = personReader.transform(ujson.parse(json))
val json = personWriter.transform(person, ujson.StringRenderer()).toStringWraps values for flexible transformation between formats.
/**
* Wraps a value for transformation operations
* @param t Value to wrap
*/
case class transform[T: Writer](t: T) extends upack.Readable with ujson.Readable {
def transform[V](f: Visitor[_, V]): V
def to[V](f: Visitor[_, V]): V
def to[V](implicit f: Reader[V]): V
}Usage Examples:
import upickle.default._
val person = Person("Alice", 30)
// Transform to different formats
val jsonValue = transform(person).to[ujson.Value]
val msgValue = transform(person).to[upack.Msg]
val backToPerson = transform(person).to[Person]
// Transform with custom visitor
val customResult = transform(person).transform(myCustomVisitor)Web-optimized APIs for Scala.js environments.
/**
* Web-optimized JSON reading for Scala.js (import upickle.web._)
* @param s JSON string input
* @return Deserialized Scala value of type T
*/
def web.read[T: Reader](s: String): T
/**
* Web-optimized JSON writing for Scala.js (import upickle.web._)
* @param t Value to serialize
* @param indent Indentation level for pretty printing
* @return JSON string representation
*/
def web.write[T: Writer](t: T, indent: Int = -1): StringUsage Examples:
// Scala.js only - optimized for browser environments
import upickle.web._
case class WebData(id: String, timestamp: Double, userAgent: String)
// Fast JSON operations in browser
val webData = WebData("user123", js.Date.now(), window.navigator.userAgent)
// Optimized serialization for web APIs
val json = web.write(webData)
// Send to server or store in browser
localStorage.setItem("userData", json)
// Read back from browser storage
val stored = localStorage.getItem("userData")
val parsed = web.read[WebData](stored)
// Integration with browser APIs
def sendToServer(data: WebData): Unit = {
val json = web.write(data)
// XMLHttpRequest integration
val xhr = new XMLHttpRequest()
xhr.open("POST", "/api/data")
xhr.setRequestHeader("Content-Type", "application/json")
xhr.send(json)
}