view release on metacpan or  search on metacpan

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

=encoding utf8

=head1 NAME

Math::Formula::Config::YAML - load/save formulas to file in YAML

=head1 INHERITANCE

 Math::Formula::Config::YAML
   is a Math::Formula::Config

=head1 SYNOPSIS

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

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

=head1 DESCRIPTION

Write a Context to file, and read it back again.

The attributes, formulas, and fragments are written as three separate documents.

You need to have installed B<YAML::XS>, minimal version 0.81 (for security reasons)
and module C<boolean.pm>.  They are 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 yml file.
Improves base, see L<Math::Formula::Config/"Actions">

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

=over 2

=item filename => FILENAME

=back

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

Serialize the C<$context> to YAML 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 .yml

=over 2

=item filename => STRING

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

=back

=back

=head1 DETAILS

YAML has a super powerful syntax, which natively supports integers,
floats, booleans, and strings.  But it can do so much more!  (What we
are not gonna use (yet))

The Context's attributes are in the first document.  The formulas are
in the second document.  The fragments will get a place in the third
document (but are not yet supported).

On Perl, you will need YAML::XS to be able to treat booleans
correctly.  For instance, C<YAML.pm> will create a string with content
'C<true>' without quotes... which makes it a boolean.

B<. Example>

  ---
  created: =2023-02-27T15:54:54+0000
  mf_version: ''
  name: test
  updated: =2023-02-27T15:54:54+0000
  version: '1.00'
  ---
  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'
  ---

=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