POD and Makefile.PL

diff --git a/Makefile.PL b/Makefile.PL
new file mode 100644 (file)
index 0000000..c8158d3
--- /dev/null
+++ b/Makefile.PL
@@ -0,0 +1,116 @@
+use strict;
+use warnings FATAL => 'all';
+use 5.008001;
+use ExtUtils::MakeMaker;
+(do 'maint/Makefile.PL.include' or die $@) unless -f 'META.yml';
+
+WriteMakefile(
+  NAME => 'JSON::MaybeXS',
+  VERSION_FROM => 'lib/JSON/MaybeXS.pm',
+  PREREQ_PM => {
+    'JSON::PP' => '2.27202',
+    'Test::Without::Module' => '0.17',
+    (can_xs()
+      ? ('Cpanel::JSON::XS' => '2.3310')
+      : ())
+  },
+);
+
+# can we locate a (the) C compiler
+sub can_cc {
+  my @chunks = split(/ /, $Config::Config{cc}) or return;
+
+  # $Config{cc} may contain args; try to find out the program part
+  while (@chunks) {
+    return can_run("@chunks") || (pop(@chunks), next);
+  }
+
+  return;
+}
+
+# check if we can run some command
+sub can_run {
+  my ($cmd) = @_;
+
+  return $cmd if -x $cmd;
+  if (my $found_cmd = MM->maybe_command($cmd)) {
+    return $found_cmd;
+  }
+
+  require File::Spec;
+  for my $dir ((split /$Config::Config{path_sep}/, $ENV{PATH}), '.') {
+    next if $dir eq '';
+    my $abs = File::Spec->catfile($dir, $cmd);
+    return $abs if (-x $abs or $abs = MM->maybe_command($abs));
+  }
+
+  return;
+}
+
+# Can our C compiler environment build XS files
+sub can_xs {
+  # Do we have the configure_requires checker?
+  local $@;
+  eval "require ExtUtils::CBuilder; ExtUtils::CBuilder->VERSION(0.27)";
+  if ( $@ ) {
+    # They don't obey configure_requires, so it is
+    # someone old and delicate. Try to avoid hurting
+    # them by falling back to an older simpler test.
+    return can_cc();
+  }
+
+  # Do we have a working C compiler
+  my $builder = ExtUtils::CBuilder->new(
+    quiet => 1,
+  );
+  unless ( $builder->have_compiler ) {
+    # No working C compiler
+    return 0;
+  }
+
+  # Write a C file representative of what XS becomes
+  require File::Temp;
+  my ( $FH, $tmpfile ) = File::Temp::tempfile(
+    "compilexs-XXXXX",
+    SUFFIX => '.c',
+  );
+  binmode $FH;
+  print $FH <<'END_C';
+#include "EXTERN.h"
+#include "perl.h"
+#include "XSUB.h"
+
+int main(int argc, char **argv) {
+    return 0;
+}
+
+int boot_sanexs() {
+    return 1;
+}
+
+END_C
+  close $FH;
+
+  # Can the C compiler access the same headers XS does
+  my @libs   = ();
+  my $object = undef;
+  eval {
+    local $^W = 0;
+    $object = $builder->compile(
+      source => $tmpfile,
+    );
+    @libs = $builder->link(
+      objects     => $object,
+      module_name => 'sanexs',
+    );
+  };
+  my $result = $@ ? 0 : 1;
+
+  # Clean up all the build files
+  foreach ( $tmpfile, $object, @libs ) {
+    next unless defined $_;
+    1 while unlink;
+  }
+
+  return $result;
+}

diff --git a/lib/JSON/MaybeXS.pm b/lib/JSON/MaybeXS.pm
index 3e4f1b3..9f740ad 100644 (file)
--- a/lib/JSON/MaybeXS.pm
+++ b/lib/JSON/MaybeXS.pm
@@ -4,6 +4,8 @@ use strict;
 use warnings FATAL => 'all';
 use base qw(Exporter);
 
+our $VERSION = '1.000000';
+
 BEGIN {
   our $JSON_Class;
 
@@ -30,3 +32,82 @@ our @EXPORT = qw(encode_json decode_json JSON);
 sub JSON () { our $JSON_Class }
 
 1;
+
+=head1 NAME
+
+JSON::MaybeXS - use L<Cpanel::JSON::XS> with a fallback to L<JSON::PP>
+
+=head1 SYNOPSIS
+
+  use JSON::MaybeXS;
+
+  my $data_structure = decode_json($json_input);
+
+  my $json_output = encode_json($data_structure);
+
+  my $json = JSON->new;
+
+=head1 DESCRIPTION
+
+This module tries to load L<Cpanel::JSON::XS>, and if that fails instead
+tries to load L<JSON::PP>. If neither is available, an exception will be
+thrown.
+
+It then exports the C<encode_json> and C<decode_json> functions from the
+loaded module, along with a C<JSON> constant that returns the class name
+for calling C<new> on.
+
+=head1 EXPORTS
+
+All of C<encode_json>, C<decode_json> and C<JSON> are exported by default.
+
+To import only some symbols, specify them on the C<use> line:
+
+  use JSON::MaybeXS qw(encode_json decode_json); # functions only
+
+  use JSON::MaybeXS qw(JSON); # JSON constant only
+
+=head2 encode_json
+
+This is the C<encode_json> function provided by the selected implementation
+module, and takes a perl data stucture which is serialised to JSON text.
+
+  my $json_text = encode_json($data_structure);
+
+=head2 decode_json
+
+This is the C<decode_json> function provided by the selected implementation
+module, and takes a string of JSON text to deserialise to a perl data structure.
+
+  my $data_structure = decode_json($json_text);
+
+=head2 JSON
+
+The C<JSON> constant returns the selected implementation module's name for
+use as a class name - so:
+
+  my $json_obj = JSON->new; # returns a Cpanel::JSON::XS or JSON::PP object
+
+and that object can then be used normally:
+
+  my $data_structure = $json_obj->decode($json_text); # etc.
+
+=head1 AUTHOR
+
+mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
+
+=head1 CONTRIBUTORS
+
+None yet. Well volunteered? :)
+
+=head1 COPYRIGHT
+
+Copyright (c) 2013 the C<JSON::MaybeXS> L</AUTHOR> and L</CONTRIBUTORS>
+as listed above.
+
+=head1 LICENSE
+
+This library is free software and may be distributed under the same terms
+as perl itself.
+
+=cut

diff --git a/maint/Makefile.PL.include b/maint/Makefile.PL.include
new file mode 100644 (file)
index 0000000..993a293
--- /dev/null
+++ b/maint/Makefile.PL.include
@@ -0,0 +1,7 @@
+BEGIN { -e 'Distar' or system("git clone git://git.shadowcat.co.uk/p5sagit/Distar.git") }
+use lib 'Distar/lib';
+use Distar;
+
+author 'mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>';
+
+1;