NAME

JSON::DJARE::Writer

VERSION

version 0.01

DESCRIPTION

Simple writer of DJARE documents

SYNOPSIS

  my $writer = JSON::DJARE::Writer->new(
      djare_version  => '0.0.1', # required
      meta_version   => '0.1.1', # required

      meta_from      => 'my-api' # optional
      auto_timestamp => 1,       # default 0, also accepts coderef
  );

  my $success = $writer->data(
      { foo => 'bar' },
      from => 'my-other-api' # optional if set in constructor
  );

  my $error = $writer->error(
      "something went wrong", # title
      schema => 'schema-id',  # optional schema
      id => "12345",          # other optional fields
  );

  ### JSON

  # There's a _json version of both producer methods that returns a JSON string
  my $json = $writer->data_json(
  my $json = $writer->error_json(

  # But if you want to mess around with the document you've created before
  # encoding it, there's a to_json method that'll help
  my $doc = $writer->data(
  $doc->{'meta'}->{'trace'} = "x12345";
  my $json = $writer->to_json( $doc )

DJARE

DJARE is documented https://github.com/pjlsergeant/dumb-json-api-response-envelope|elsewhere and this document neither discusses or documents DJARE itself.

METHODS

new

Instantiates a new writer object.

Options:

• djare_version - required. The version of DJARE you want to produce. The only possible value for this (at the time of writing) is 0.0.1.

• meta_version - required. The version number to include in the DJARE `meta/version` section. This is a SemVer.

• meta_from - optional. A DJARE document needs a meta/from field. You can either specify this for all documents this object will produce here, or you can set it at document creation time

• meta_schema - optional. A DJARE document may include a meta/schema field. You can either specify this for all documents this object will produce here, or you can set it at document creation time

data

data_json

 ->data( payload, options )
 ->data( { quis => 'ego' }, from => 'scrambles' )

First argument is the data payload, and the other arguments are a hash of options, of which the only definable one is from, for overriding meta/from. Returns a Perl hashref.

data_json is the same thing, but returns JSON.

error

error_json

 ->error( title, options )
 ->error( "didn't work", id => 4532 )

First argument is the data payload, and the other arguments are a hash of options, of which the only definable one is from, for overriding meta/from. Returns a Perl hashref.

All keys will be stringified except trace, except undefined keys, which will be dropped rather than turned into an empty string.

data_json is the same thing, but returns JSON.

to_json

Convenience method to the same JSON stringifier the *_json methods use.

Literally just: $self-{'_json'}->encode($payload)>

auto_timestamp

The default timestamp creator, which is what's used if you instantiate with <auto_timestamp = 1>>. Uses gmtime(time) as its base.

cpanm JSON::DJARE::Writer

perl -MCPAN -e shell
install JSON::DJARE::Writer