TableDef/lib/TableDef.pod
## no critic: TestingAndDebugging::RequireUseStrict
# PODNAME: TableDef
# AUTHORITY
# DATE
our $DIST = 'TableDef'; # DIST
# VERSION
1;
# ABSTRACT: Table data definition
__END__
=pod
=encoding UTF-8
=head1 NAME
TableDef - Table data definition
=head1 SPECIFICATION VERSION
1
=head1 VERSION
This document describes version 1.0.9 of TableDef (from Perl distribution TableDef), released on 2023-05-24.
=head1 ABSTRACT
This document describes TableDef, a way to define table data.
=head1 SPECIFICATION
In this document, hashes are written in JSON or pseudo-JSON (e.g. contains
ellipsis C<...> or JavaScript-style comments C<// ...>).
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL "NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in RFC 2119.
A TableDef spec is written in L<DefHash>. It can be used to describe the
structure of a relational database table, a CSV file, or an array of hashes.
Tools can be written to convert a TableDef hash to SQL's CREATE TABLE statement,
or to utilize information in the TableDef hash to format an HTML table, to view
a DB grid on the web browser, etc.
=head2 Properties
=head3 summary => str
From DefHash. Table summary.
=head3 description => str
From DefHash. Table longer description.
=head3 tags => array
From DefHash.
=head3 fields => hash
A hash, where the keys are field names and the values field specification. See
L</"FIELD SPECIFICATION">.
=head3 pk => str | array
Specify the primary key for the table. Either a string containing a single field
name, or an array of field names (for multi-field key).
=head1 FIELD SPECIFICATION
A L<DefHash>.
=head2 Properties
=head3 schema* => str | array
L<Sah> schema. This property is required.
=head3 summary => str
From DefHash. Field summary.
=head3 description => str
From DefHash. Field longer description.
=head3 tags => array
From DefHash.
=head3 pos => int
Specify the order of field. Must start from 0 and be contiguous.
=head3 req => bool (default: 0)
Whether this field is mandatory to be present. If 0, then function can choose to
omit the field.
=head3 sortable => bool (default: 1)
Specify whether this field can be sorted.
=head3 filterable => bool (default: 1)
Specify whether this field can be used as a filter.
=head3 unique => bool
Specify whether this field must contain unique values.
=head3 include_by_default => bool (default: 1)
This specifies that this field should be shown or included on "default view".
What default view is will depend on the context or implementation. Usually you
can set this to 0 if the field content is too long or wide. For example, in Perl
module L<Perinci::Sub::Gen::AccessTable>, if you give C<< detail => 1 >> to the
generated function, it will include all fields except fields that has this
property set to 0. To include such fields, you'll need to explicitly issue C<<
with.FIELDNAME => 1 >>.
=head1 HOMEPAGE
Please visit the project's homepage at L<https://metacpan.org/release/TableDef>.
=head1 SOURCE
Source repository is at L<https://github.com/perlancar/perl-TableDef>.
=head1 SEE ALSO
L<DefHash>
=head1 AUTHOR
perlancar <perlancar@cpan.org>
=head1 CONTRIBUTING
To contribute, you can send patches by email/via RT, or send pull requests on
GitHub.
Most of the time, you don't need to build the distribution yourself. You can
simply modify the code, then test via:
% prove -l
If you want to build the distribution (e.g. to try to install it locally on your
system), you can install L<Dist::Zilla>,
L<Dist::Zilla::PluginBundle::Author::PERLANCAR>,
L<Pod::Weaver::PluginBundle::Author::PERLANCAR>, and sometimes one or two other
Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond
that are considered a bug and can be reported to me.
=head1 COPYRIGHT AND LICENSE
This software is copyright (c) 2023, 2016, 2015, 2014 by perlancar <perlancar@cpan.org>.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
=head1 BUGS
Please report any bugs or feature requests on the bugtracker website L<https://rt.cpan.org/Public/Dist/Display.html?Name=TableDef>
When submitting a bug or request, please include a test-file or a
patch to an existing test-file that illustrates the bug or desired
feature.
=cut