guardian / nitf-scala

Scala library to parse and generate News Industry Text Format files

GitHub

nitf-scala

License: Apache-2.0 Build Status Codacy Quality Rating Latest release for Scala 2.11 Latest release for Scala 2.12

Scala library to parse and generate News Industry Text Format files, based on ScalaXB.

This library supports versions 3.3 to 3.6.
(Previous versions don't have an XSD.)

Usage

To use this library, add the following dependencies to your project:

val nitfScalaVersion = "3.6.2"  // one of 3.3, 3.4, 3.5, and 3.6 followed by the release version
val scalaXmlVersion = "1.1.0"
libraryDependencies ++= Seq(
  "org.scala-lang.modules" %% "scala-xml" % scalaXmlVersion,
  "org.scala-lang.modules" %% "scala-parser-combinators" % scalaXmlVersion,
  "com.gu" %% "nitf-scala" % nitfScalaVersion
)

This is an example of how to parse XML into NITF:

import com.gu.nitf.model._
import com.gu.nitf.scalaxb._

val doc = scalaxb.fromXML[Nitf](
  <nitf>
    <head><title>Hello</title></head>
    <body><body.content>World</body.content></body>
  </nitf>
)

This is an example of how to create an NITF tree:

import com.gu.nitf.model.builders._

val doc = new NitfBuilder()
  .withHead(new HeadBuilder().withTitle("News Article"))
  .withBody(new BodyBuilder()
    .withContent(new BodyContentBuilder()
      .withParagraph(new ParagraphBuilder().withText("That's it, really!"))
  ))
  .build

val xml = scalaxb.toXML(doc, None, None, BareNitfNamespace)

Specifications

NITF schema, documentation, and examples are available from IPTC. This archive contains all of this for versions 2.5 to 3.6.

The schemas used to generate the classes in this project are available in the schema folder.

Generated Sources

The source files were generated using an unreleased version of ScalaXB that was built from source. Hopefully, it will be released in the main repository soon.

The following command was used to generate the files:

for v in 3.{3..6}; do
  scalaxb "src/test/resources/nitf-$v.xsd" \
    --outdir "src/main/$v" \
    --no-dispatch-client \
    --named-attributes \
    --capitalize-words \
    --symbol-encoding-strategy=discard \
    --default-package com.gu.nitf.model \
    --protocol-package com.gu.nitf.scalaxb
done

Building

To build this project from source, run:

sbt clean +compile +test

Note that a clean build may take up to 10 minutes. You may also need to increase the memory available to sbt (e.g. using -mem).
(The full compilation has more than 24k class files!)

The project is set up to build against Scala 2.11 and Scala 2.12.