Packages

  • package root
    Definition Classes
    root
  • package io
    Definition Classes
    root
  • package dylemma
    Definition Classes
    io
  • package spac

    SPaC (short for "Streaming Parser Combinators") is a library for building stream consumers in a declarative style, specialized for tree-like data types like XML and JSON.

    SPaC (short for "Streaming Parser Combinators") is a library for building stream consumers in a declarative style, specialized for tree-like data types like XML and JSON.

    Many utilities for handling XML and JSON data involve parsing the entire "document" to some DOM model, then inspecting and transforming that model to extract information. The downside to these utilities is that when the document is very large, the DOM may not fit in memory. The workaround for this type of problem is to treat the document as a stream of "events", e.g. "StartElement" and "EndElement" for XML, or "StartObject" and "EndObject" for JSON. The downside to this workaround is that writing code to handle these streams can be complicated and error-prone, especially when the DOM is complicated.

    SPaC's goal is to drastically simplify the process of creating code to handle these streams.

    This package contains the "core" SPaC traits; Parser, Transformer, Splitter, and ContextMatcher.

    See the xml and json subpackages (provided by the xml-spac and json-spac libraries respectively) for specific utilities related to handling XML and JSON event streams.

    Definition Classes
    dylemma
  • package interop
    Definition Classes
    spac
  • package json

    This package provides extensions to the core "spac" library which allow for the handling of JSON data.

    This package provides extensions to the core "spac" library which allow for the handling of JSON data.

    Rather than creating explicit classes that extend Parser, Transformer, and Splitter, this package provides type aliases and implicit extensions. For example, JsonParser[A] is just a type alias for Parser[JsonEvent, A], and JsonParser is just a call to Parser[JsonEvent].

    Implicit JsonParsers are available for each of the JSON primitive types:

    • string
    • number (expressed as Int, Long, Float, or Double)
    • boolean
    • null (expressed as None.type)

    Helpers are available for parsing JSON arrays and objects:

    • JsonParser.listOf[A] to parse an array where each value is an A
    • JsonParser.objectOf[A] to parse an object where the value for each field an A
    • JsonParser.objectOfNullable[A] to parse an object where the value for each field is either null or an A, filtering out the nulls
    • JsonParser.fieldOf[A](fieldName) to parse a specific field from an object

    A DSL for creating json-specific ContextMatchers is provided to make it more convenient to call Splitter.json. For example:

    Splitter.json("foo" \ "bar").as[String].parseFirst

    Can be used to capture rootJson.foo.bar as a String in

    {
      "foo": {
        "bar": "hello"
      }
    }

    To "split" values inside arrays, index-related context matchers are available, e.g.

    Splitter.json("foo" \ anyIndex).as[Int].parseToList

    Can be used to capture each of the numbers in the "foo" array in

    {
      "foo": [1, 2, 3]
    }

    A note about JsonEvents in spac: JSON doesn't have any explicit markers for when a field ends, or when an array index starts or ends; those context changes are essentially inferred by the presence of some other event. For example, instead of a "field end" event, typically there will be either a new "field start" or a token representing the end of the current object. With spac, splitters and context matchers generally operate under the assumption that a "stack push" event (like a field start) will eventually be followed by a corresponding "stack pop" event (i.e. field end).

    To allow for this, these "inferred" events (FieldEnd, IndexStart, IndexEnd) are explicitly represented as JsonEvents in the stream being parsed. Keep this in mind when creating JSON ContextMatchers:

    • field-related matchers will match a stack like case ObjectStart :: FieldStart(_) :: _
    • index-related matchers will match a stack like case ArrayStart :: IndexStart(_) :: _
    Definition Classes
    spac
  • package xml

    This package provides extensions to the core "spac" library which allow for the handling of XML data.

    This package provides extensions to the core "spac" library which allow for the handling of XML data.

    Rather than creating explicit classes that extend Parser, Transformer, and Splitter, this package provides type aliases and implicit extensions. For example, XmlParser[A] is just a type alias for Parser[XmlEvent, A], and XmlParser is just a call to Parser[XmlEvent].

    Three main Parser methods are added to Parser[XmlEvent] via the XmlParserApplyOps implicit class:

    • XmlParser.forText - for capturing raw text
    • XmlParser.attr - for capturing mandatory attributes from elements
    • XmlParser.attrOpt - for capturing optional attributes from elements

    One main Splitter constructor method is added to Splitter via the XmlSplitterApplyOps implicit class:

    • Splitter.xml - for creating splitters based on an inspection of an "element stack"

    Three main Splitter member methods are added to Splitter[XmlEvent, C] via the XmlSplitterOps implicit class:

    • .attr - alias for .joinBy(XmlParser.attr(...))
    • .attrOpt - alias for .joinBy(XmlParser.attrOpt(...))
    • .text - alias for .joinBy(XmlParser.forText)

    A DSL for creating xml-specific ContextMatchers is provided to make it more convenient to call Splitter.xml. For example:

    Splitter.xml("things" \ "thing").attr("foo").parseToList

    Can be used to capture a list of the "foo" attributes in the <thing> elements in

    <things>
       <thing foo="hello" />
       <thing foo="Goodbye">
          <extra>junk</extra>
       </thing>
    </thing>
    Definition Classes
    spac
  • AsQName
  • Fs2DataQName
  • Fs2DataSource
  • JavaxQName
  • JavaxSource
  • XmlEvent
  • XmlParserApplyOps
  • XmlSpacException
  • XmlSplitterApplyOps
  • XmlSplitterOps

package xml

This package provides extensions to the core "spac" library which allow for the handling of XML data.

Rather than creating explicit classes that extend Parser, Transformer, and Splitter, this package provides type aliases and implicit extensions. For example, XmlParser[A] is just a type alias for Parser[XmlEvent, A], and XmlParser is just a call to Parser[XmlEvent].

Three main Parser methods are added to Parser[XmlEvent] via the XmlParserApplyOps implicit class:

  • XmlParser.forText - for capturing raw text
  • XmlParser.attr - for capturing mandatory attributes from elements
  • XmlParser.attrOpt - for capturing optional attributes from elements

One main Splitter constructor method is added to Splitter via the XmlSplitterApplyOps implicit class:

  • Splitter.xml - for creating splitters based on an inspection of an "element stack"

Three main Splitter member methods are added to Splitter[XmlEvent, C] via the XmlSplitterOps implicit class:

  • .attr - alias for .joinBy(XmlParser.attr(...))
  • .attrOpt - alias for .joinBy(XmlParser.attrOpt(...))
  • .text - alias for .joinBy(XmlParser.forText)

A DSL for creating xml-specific ContextMatchers is provided to make it more convenient to call Splitter.xml. For example:

Splitter.xml("things" \ "thing").attr("foo").parseToList

Can be used to capture a list of the "foo" attributes in the <thing> elements in

<things>
   <thing foo="hello" />
   <thing foo="Goodbye">
      <extra>junk</extra>
   </thing>
</thing>
Source
package.scala
Linear Supertypes
AnyRef, Any
Ordering
  1. Grouped
  2. Alphabetic
  3. By Inheritance
Inherited
  1. xml
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. Protected

Type Members

  1. trait AsQName[N] extends AnyRef

    Adapter for various representations of QName

  2. type ElemContextMatcher[+A] = SingleItemContextMatcher[ElemStart, A]

  3. type XmlContextMatcher[+Context] = ContextMatcher[ElemStart, Context]

  4. sealed trait XmlEvent extends HasLocation

    Spac's internal representation of XML "events".

    Spac's internal representation of XML "events". Third-party xml streaming classes like javax.xml.stream or fs2-data can be supported by providing an AsXmlEvent implementation which converts the third-party event type into this type.

  5. type XmlParser[+Out] = Parser[XmlEvent, Out]

    Type alias for a Parser whose input type is XmlEvent.

  6. implicit final class XmlParserApplyOps extends AnyVal

    XML-specific Parser constructor methods, for example XmlParser.attr and XmlParser.text

  7. trait XmlSpacException[Self <: XmlSpacException[Self]] extends SpacException[Self]

    SpacException subtype for XML-specific exceptions

  8. type XmlSplitter[+C] = Splitter[XmlEvent, C]

  9. implicit final class XmlSplitterApplyOps extends AnyVal

    Adds Splitter.xml, for constructing element matcher-based XmlSplitters.

  10. implicit class XmlSplitterOps[C] extends AnyRef

    XML-specific Splitter member methods, for example: attr, attrOpt, and text,

  11. type XmlTransformer[+Out] = Transformer[XmlEvent, Out]

Deprecated Type Members

  1. type XMLContextMatcher[+Context] = ContextMatcher[ElemStart, Context]
    Annotations
    @deprecated
    Deprecated

    (Since version v0.9) Use XmlContextMatcher (with lowercase 'ml') instead

  2. type XMLParser[+Out] = Parser[XmlEvent, Out]
    Annotations
    @deprecated
    Deprecated

    (Since version v0.9) Use XmlParser (with lowercase 'ml') instead

  3. type XMLSplitter[+C] = Splitter[XmlEvent, C]
    Annotations
    @deprecated
    Deprecated

    (Since version v0.9) Use XmlSplitter (with lowercase 'ml') instead

Value Members

  1. val *: ElemContextMatcher[Unit]

    Context matcher that matches any single element at the head of the tag stack.

  2. val **: XmlContextMatcher[Unit]

    Context matcher that matches any number of elements from the head of the tag stack.

  3. val Root: XmlContextMatcher[Unit]

    Context matcher that always matches without consuming any of the tag stack.

  4. val XmlParser: ParserApplyWithBoundInput[XmlEvent]

    Like the Parser companion object, but only for creating Parsers whose input type is XmlEvent.

    Like the Parser companion object, but only for creating Parsers whose input type is XmlEvent.

    See also

    XmlParserApplyOps

  5. val XmlSplitter: SplitterApplyWithBoundInput[XmlEvent]

  6. val XmlTransformer: TransformerApplyWithBoundInput[XmlEvent]

  7. def attr[N](attrName: N)(implicit arg0: AsQName[N]): ElemContextMatcher[String]

    Context matcher that extracts the given attribute from the element at the head of the stack.

    Context matcher that extracts the given attribute from the element at the head of the stack.

    N

    The name *type* - usually String, but can be any member of the AsQName typeclass. Note that for javax.xml.namespace.QName you will need to include the "spac-javax" support library.

    attrName

    The name of the attribute to extract

  8. def attrOpt[N](attrName: N)(implicit arg0: AsQName[N]): ElemContextMatcher[Option[String]]

    Context matcher that extracts the given optional attribute from the element at the head of the stack.

    Context matcher that extracts the given optional attribute from the element at the head of the stack. If the attribute is missing from the head element, this matcher will succeed with a result of None, as opposed to the attr matcher which would fail.

    N

    The name *type* - usually String, but can be any member of the AsQName typeclass. Note that for javax.xml.namespace.QName you will need to include the "spac-javax" support library.

    attrName

    The name of the attribute to extract

  9. implicit def elem[N](elemName: N)(implicit N: AsQName[N]): ElemContextMatcher[Unit]

    Context matcher that matches the element at the head of the stack as long as its name matches the given elemName

    Context matcher that matches the element at the head of the stack as long as its name matches the given elemName

    This is normally called implicitly, e.g. with Splitter.xml("foo" \ "bar"), but of course can be called explicitly, e.g. val matcher = elem("foo") \ elem("bar")

    N

    The name *type* - usually String, but can be any member of the AsQName typeclass. Note that for javax.xml.namespace.QName you will need to include the "spac-javax" support library.

    elemName

    The name of the element.

  10. def extractElemName: ElemContextMatcher[String]

    Context matcher that extracts the (local) name of the element at the head of the stack.

    Context matcher that extracts the (local) name of the element at the head of the stack. Acts as a convenience for extractElemQName[String]

  11. def extractElemQName[N](implicit arg0: AsQName[N]): ElemContextMatcher[N]

    Context matcher that extracts the (qualified) name of the element at the head of the stack.

    Context matcher that extracts the (qualified) name of the element at the head of the stack. The type-level representation of the name is chosen by the caller

    N

    The representation of the element's qualified name. This could be String, but in that case you should use extractElemName instead. For QName types such as the one from javax.xml, you must import a corresponding support package.

  12. object AsQName

  13. object Fs2DataQName

  14. object Fs2DataSource

    Provides helpers for creating FS2 streams of io.dylemma.spac.xml.XmlEvent, using fs2-data-xml as the underlying event provider.

    Provides helpers for creating FS2 streams of io.dylemma.spac.xml.XmlEvent, using fs2-data-xml as the underlying event provider.

    Fs2-data is already pretty "plug-and-play", so at best this helper just removes a few steps/pipes that you would have to manually call.

    For example:

    val charStream: Stream[IO, Char] = ???
    
    // this...
    val xmlStream1: Stream[IO, XmlEvent] = {
      import fs2.data.xml._
      charStream
        .through(events)
        .through(namespaceResolver)
        .through(reverenceResolver())
        .through(normalize)
        .through(Fs2DataSource.convert)
    }
    
    // could be replaced with
    val xmlStream2: Stream[IO, XmlEvent] = {
      Fs2DataSource.fromRawXmlStream(charStream)
    }

    Essentially this helper just provides a convenient apply method that accepts String, Stream[F, Char], Stream[F, String], or Stream[F, fs2.data.xml.XmlEvent] to return a Stream[F, XmlEvent] which an XmlParser could then interact with.

  15. object JavaxQName

  16. object JavaxSource

    Provides helpers for creating Source[XmlEvent] using javax.xml.stream for the underlying event provider.

  17. object XmlEvent

  18. object XmlSpacException extends Serializable

    Contains the actual XmlSpacException subtypes

Deprecated Value Members

  1. val XMLParser: ParserApplyWithBoundInput[XmlEvent]
    Annotations
    @deprecated
    Deprecated

    (Since version v0.9) Use XmlParser (with lowercase 'ml') to reference the parser companion

  2. val XMLSplitter: SplitterApplyWithBoundInput[XmlEvent]
    Annotations
    @deprecated
    Deprecated

    (Since version v0.9) Use XmlSplitter (with lowercase 'ml') for directly referencing the companion object, or use Splitter.xml to construct a new XmlSplitter

Inherited from AnyRef

Inherited from Any

XML-specific extensions for Parser and Splitter

XML-specific Type and Value aliases

XML Context Matcher Construction

XML Event Representation

Backend Parser Support

Ungrouped