view release on metacpan or  search on metacpan

lib/Math/Formula/Config/JSON.pod  view on Meta::CPAN

=encoding utf8

=head1 NAME

Math::Formula::Config::JSON - load/save formulas to file

=head1 INHERITANCE

 Math::Formula::Config::JSON
   is a Math::Formula::Config

=head1 SYNOPSIS

  my $context = Math::Formula::Content->new(name => 'test');
  my $config = Math::Formula::Config::JSON->new(directory => $dir);

  $config->save($context);
  my $context = $config->load('test');

=head1 DESCRIPTION

Save and load a L<Math::Formula::Context|Math::Formula::Context> to JSON files.

You need to B<have installed Cpanel::JSON::XS>.  That module is not in the
dependencies of this packages, because we do not want to add complications
to the main code.

Extends L<"DESCRIPTION" in Math::Formula::Config|Math::Formula::Config/"DESCRIPTION">.

=head1 METHODS

Extends L<"METHODS" in Math::Formula::Config|Math::Formula::Config/"METHODS">.

=head2 Constructors

Extends L<"Constructors" in Math::Formula::Config|Math::Formula::Config/"Constructors">.

=over 4

=item $class-E<gt>B<new>(%options)

Inherited, see L<Math::Formula::Config/"Constructors">

=back

=head2 Attributes

Extends L<"Attributes" in Math::Formula::Config|Math::Formula::Config/"Attributes">.

=over 4

=item $obj-E<gt>B<directory>()

Inherited, see L<Math::Formula::Config/"Attributes">

=item $obj-E<gt>B<path_for>($file)

Inherited, see L<Math::Formula::Config/"Attributes">

=back

=head2 Actions

Extends L<"Actions" in Math::Formula::Config|Math::Formula::Config/"Actions">.

=over 4

=item $obj-E<gt>B<load>($name, %options)

Load a L<Math::Formula::Context|Math::Formula::Context> for a file in JSON serialization.
Improves base, see L<Math::Formula::Config/"Actions">

 -Option  --Default
  filename  <directory/$name.json>

=over 2

=item filename => FILENAME

=back

=item $obj-E<gt>B<save>($context, %options)

Serialize the C<$context> to JSON files, as storage or to be edited by hand.
This is a useful method when default configuration templates need to be generated.
Improves base, see L<Math::Formula::Config/"Actions">

 -Option  --Default
  filename  $context->name .json

=over 2

=item filename => STRING

Save under a different filename than derived from the name of the context.

=back

=back

=head1 DETAILS

JSON seems to be everyone's favorite serialization syntax, nowadays.  It natively
supports integers, floats, booleans, and strings.  Formulas get a leading C<=>
(not configurable (yet)).

B<. Example>

  {
    "created" : "2023-02-28T16:30:27+0000",
    "formulas" : {
       "expr1" : "=1 + 2 * 3",
       "expr2" : "=\"abc\".size + 3k; returns='MF::INTEGER'",
       "fakes" : false,
       "float" : 3.14,
       "int" : 42,
       "longer" : "abc def yes no",
       "no_quotes" : "abc",
       "some_truth" : true,
       "string" : "true"
    },
    "mf_version" : "",
    "name" : "test",
    "updated" : "2023-02-28T16:30:27+0000",
    "version" : 1.0
  }

=head1 DIAGNOSTICS

=over 4

=item Fault: Error on close while saving '$name' to $file: $!

Z<>

=item Error: Save directory '$dir' does not exist

Z<>

=item Error: Save directory required

Z<>

=item Fault: Trying to save context '$name' to $file: $!

Z<>

=item Warning: cannot (yet) save CODE, skipped '$name'

Z<>

=back

=head1 SEE ALSO

This module is part of Math-Formula version 0.18,
built on August 19, 2025. Website: F<http://perl.overmeer.net/CPAN/>

=head1 LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2023-2025 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.