Welcome to the Hydrant Documentation

Hydrant is a simple object serializer and data mapper library. Its goal is to parse JSON into value objects that you can safely use throughout your application. All the input validation and error checking can be done through Hydrant.

New? Install Hydrant and then jump in with getting started.

Topical guides after getting started

• Learn how Hydrant’s error handling system works
• Read up on mapping techniques for some parsing scenarios that Hydrant can handle.
• Understand Hydrant’s design
• Learn how to write your own mappers.

Hydrant’s Public API reference

• HYDMappers
• HYDAccessors
• NSFormatters
• NSValueTransformers

About Hydrant’s Development

• Review what’s changed between versions.
• Read the Contributor’s Guide.
• Bugs? File bugs on GitHub. Don’t know the best way? Read filing bugs.

Table of Contents

• Installation
• Getting Started
  • The Problem
  • Serializing with Hydrant
  • Why not manully parse the JSON?
  • Error Handling
  • Marking fields as Optional
  • Converting it back to JSON
  • Removing Boilerplate
    • Using Reflection to Remove the Boilerplate
• Handling Hydrant Errors
  • Debugging Parse Errors
  • Reading Information from Hydrant Errors
  • Creating Hydrant Errors
• Mapping Techniques
  • Convert a value or return nil (or another default value)
  • How do I return a source object’s value unchanged?
  • Mapping an array of objects, excluding invalid ones instead of failing entirely
  • Mapping Two Fields to One Property
• Writing Your Own Mappers
  • Thought Process
  • Raising Exceptions
  • Crafting your Implementation
  • Closing Thoughts
• Design
  • Philosophies
    • Composition over Inheritance
    • Immutability over Mutability
    • Abstractions over Concretions
    • Have Small Abstractions
    • Test-Driven Code
  • Mapper Protocol
  • Accessor Protocol
    • Accessors & Mappers
  • Mapping Data Structure
  • How do you have function overloading without being Objective-C++?
  • Trade-offs
• Mapper Reference
  • Thread Safety
  • Constructor Helper Functions
  • The Reverse Mapper
  • HYDMapEnum
  • HYDMapIdentity
  • HYDMapObjectToStringByFormatter
  • HYDMapStringToObjectByFormatter
  • HYDMapDateToNumberSince
  • HYDMapNumberToDateSince
  • HYDMapDateToString
  • HYDMapStringToDate
  • HYDMapStringToNumber
  • HYDMapNumberToString
  • HYDMapURLToString
  • HYDMapStringToURL
  • HYDMapUUIDToString
  • HYDMapStringToUUID
  • HYDMapValue
  • HYDMapReverseValue
  • HYDMapForward
  • HYDMapBackward
  • HYDMapCollectionOf / HYDMapArrayOf
  • HYDMapFirst
  • HYDMapSplit
  • HYDMapNonFatally
  • HYDMapNotNull
  • HYDMapOptionally
  • HYDMapTypes
  • HYDMapKVCObject
  • HYDMapObject
  • HYDMapWithBlock
  • HYDMapWithPostProcessing
  • HYDMapReflectively
  • HYDMapThread
  • HYDMapDispatch
• Accessor Reference
  • HYDAccessKeyPath
  • HYDAccessKey
  • HYDAccessIndex
  • HYDAccessDefault
• Formatter Reference
  • Date Format Strings
  • HYDDotNetDateFormatter
  • HYDURLFormatter
  • HYDUUIDFormatter
• Value Transformer Reference
  • HYDBlockValueTransformer
  • HYDIdentityValueTransformer
  • HYDReversedValueTransformer
  • HYDCamelToSnakeCaseValueTransformer
• Contributing to Hydrant
  • Filing Bugs
  • Contributing Code
• Changelog
  • Master (bleeding edge)