Changeset 18088 for ext

Show
Ignore:
Timestamp:
09/22/07 01:04:40 (16 months ago)
Author:
Darren_Duncan
Message:

ext/Muldis-DB/ : large SeeAlso?.pod update, various small docs updates

Location:
ext/Muldis-DB
Files:
7 modified

Legend:

Unmodified
Added
Removed

  • ext/Muldis-DB/Changes

    r17897 r18088  
    2020    t/MDB_10_Literal_Simple.t test file. 
    2121 
    22     * New file versions are: DB.pm and Interface.pm and Validator.pm and 
    23     Example.pm 0.4.0.  The other pre-existing versioned files are 
    24     unchanged. 
     22    * All versioned files had their version numbers brought up to 0.4.0. 
    2523 
    2624    * (DB.pm, Interface.pm, Example.pm)  Updates to various 
    … …  
    2826    DESCRIPTION of DB.pm.  Added a small initial DESCRIPTION to each of 
    2927    Interface.pm, Example.pm.  Further minor edits to other sections. 
     28 
     29    * Minor updates to all versioned files such that most references to the 
     30    project name were changed to "Muldis DB" from "Muldis::DB". 
     31 
     32    * (SeeAlso.pod)  Updated the PROSPECTIVE MULDIS DB EXTENSIONS section 
     33    mainly to bring various names, terminology, and references up to date 
     34    with design changes.  Any package names containing "Literal" now have 
     35    "PHMD" instead, and any docs refering to "Muldis DB AST nodes" now 
     36    refer to "Perl Hosted Muldis D".  Re-added the 
     37    Muldis::DB::AST::StringRepr module that was removed in release 0.1.0 
     38    under the new name Muldis::DB::PHMD::Translate::ConcreteMuldisD (it's 
     39    not part of Literal.pm anymore).  Other small renames and changes. 
    3040 
    3141    * Updated the TODO file. 

  • ext/Muldis-DB/lib/Muldis/DB/Engine/Example.pm

    r17866 r18088  
    244244=head1 LICENSE AND COPYRIGHT 
    245245 
    246 This file is part of the Muldis::DB framework. 
    247  
    248 Muldis::DB is Copyright © 2002-2007, Darren Duncan. 
     246This file is part of the Muldis DB framework. 
     247 
     248Muldis DB is Copyright © 2002-2007, Darren Duncan. 
    249249 
    250250See the LICENSE AND COPYRIGHT of L<Muldis::DB> for details. 

  • ext/Muldis-DB/lib/Muldis/DB/Engine/Example/Operators.pm

    r17897 r18088  
    167167=head1 LICENSE AND COPYRIGHT 
    168168 
    169 This file is part of the Muldis::DB framework. 
     169This file is part of the Muldis DB framework. 
    170170 
    171 Muldis::DB is Copyright © 2002-2007, Darren Duncan. 
     171Muldis DB is Copyright © 2002-2007, Darren Duncan. 
    172172 
    173173See the LICENSE AND COPYRIGHT of L<Muldis::DB> for details. 

  • ext/Muldis-DB/lib/Muldis/DB/Engine/Example/PhysType.pm

    r17897 r18088  
    10531053=head1 LICENSE AND COPYRIGHT 
    10541054 
    1055 This file is part of the Muldis::DB framework. 
    1056  
    1057 Muldis::DB is Copyright © 2002-2007, Darren Duncan. 
     1055This file is part of the Muldis DB framework. 
     1056 
     1057Muldis DB is Copyright © 2002-2007, Darren Duncan. 
    10581058 
    10591059See the LICENSE AND COPYRIGHT of L<Muldis::DB> for details. 

  • ext/Muldis-DB/lib/Muldis/DB/Interface.pm

    r17897 r18088  
    418418    # Instantiate a Muldis::DB DBMS / virtual machine. 
    419419    my $dbms = Muldis::DB::Interface::new_dbms( 
    420             :engine_name('Muldis::DB::Engine::Example'), 
    421             :dbms_config({}), 
    422         ); 
     420        :engine_name('Muldis::DB::Engine::Example'), 
     421        :dbms_config({}), 
     422    ); 
    423423 
    424424    # TODO: Create or connect to a repository and work with it. 
    … …  
    520520=head1 BUGS AND LIMITATIONS 
    521521 
    522 The Muldis::DB framework for Perl 6 is built with a lot of code that should 
    523 be superfluous, since the Muldis::DB authors can not yet assume that a 
     522The Muldis DB framework for Perl 6 is built with a lot of code that should 
     523be superfluous, since the Muldis DB authors can not yet assume that a 
    524524number of desired Perl 6 features are actually available in the language 
    525 implementations yet, and so and so Muldis::DB includes its own substituted 
    526 implementations of those features, which have been made as part of 
    527 Muldis::DB for Perl 5 anyway due to Perl 5's relative deficiencies.  The 
     525implementations yet, and so and so Muldis DB includes its own substituted 
     526implementations of those features, which have been made as part of Muldis 
     527DB for Perl 5 anyway due to Perl 5's relative deficiencies.  The 
    528528reimplemented features include manual type-checks of routine arguments (as 
    529529if the parameters were declared C<Any>), and the use of C<Array> rather 
    … …  
    531531than C<Mapping> or C<Hash> (because non-Str keys may not be supported yet). 
    532532Also, explicit clones are made of any "read only" Array or Hash arguments 
    533 or return values, so to safeguard the Muldis::DB internals against any 
    534 subsequent mutation of them by callers.  Hopefully, Muldis::DB for Perl 6 
     533or return values, so to safeguard the Muldis DB internals against any 
     534subsequent mutation of them by callers.  Hopefully, Muldis DB for Perl 6 
    535535will be able to have its code base slimmed considerably when the Perl 6 
    536536implementations themselves are more mature. 
    … …  
    544544=head1 LICENSE AND COPYRIGHT 
    545545 
    546 This file is part of the Muldis::DB framework. 
    547  
    548 Muldis::DB is Copyright © 2002-2007, Darren Duncan. 
     546This file is part of the Muldis DB framework. 
     547 
     548Muldis DB is Copyright © 2002-2007, Darren Duncan. 
    549549 
    550550See the LICENSE AND COPYRIGHT of L<Muldis::DB> for details. 

  • ext/Muldis-DB/lib/Muldis/DB/SeeAlso.pod

    r17127 r18088  
    1616This document is a central location within the L<Muldis::DB> distribution 
    1717where any important recommendations of or links to external resources go. 
    18 This includes both resources that were helpful in making Muldis::DB, as 
    19 well as resources that are or could be related to Muldis::DB. 
     18This includes both resources that were helpful in making Muldis DB, as 
     19well as resources that are or could be related to Muldis DB. 
    2020 
    2121=head1 FORMAL SPECIFICATION 
    … …  
    2828formal implementation of by way of Muldis D. 
    2929 
    30 =head1 LIST OF PUBLIC Muldis::DB ENGINES 
     30=head1 LIST OF PUBLIC MULDIS DB ENGINES 
    3131 
    3232I<This documentation is pending.> 
    … …  
    3434L<Muldis::DB::Engine::Example>. 
    3535 
    36 =head1 PROSPECTIVE Muldis::DB EXTENSIONS 
     36=head1 PROSPECTIVE MULDIS DB EXTENSIONS 
    3737 
    3838These are some theoretical examples of other Perl modules or documentation 
    39 that could be created to work with Muldis::DB, but if so would most likely 
     39that could be created to work with Muldis DB, but if so would most likely 
    4040be distributed independently from it.  The given package names are 
    4141examples, and the examples in question could have other names if 
    … …  
    4747 
    4848Pod files with a potentially large collection of examples, tutorials, FAQs, 
    49 and so on that help people learn how to employ Muldis::DB for the things 
     49and so on that help people learn how to employ Muldis DB for the things 
    5050they need to do.  In particular, there should be a lot of help given for 
    5151people migrating from other systems that use different paradigms than 
    52 Muldis::DB does, for example SQL-using systems. 
     52Muldis DB does, for example SQL-using systems. 
    5353 
    5454The Cookbook distro may also be the main repository of executing code that 
    55 would otherwise go in the /examples directory of the Muldis::DB core 
     55would otherwise go in the /examples directory of the Muldis DB core 
    5656distro. 
    5757 
    … …  
    5959C<Muldis::DB::Engine::Genezzo> etc 
    6060 
    61 A Muldis::DB Engine built around Jeffrey Cohen's Genezzo DBMS, or 
    62 specifically the class that does C<Muldis::DB::Engine::Role>, could 
     61A Muldis DB Engine built around Jeffrey Cohen's L<Genezzo> DBMS, or 
     62specifically the root module that provides the C<new_dbms> function, could 
    6363conceivably have either of the above file or package names, depending on 
    6464what its author prefers, or something else yet.  A strong name influence 
    65 could be whether Muldis::DB forms the sole public interface for Genezzo 
     65could be whether Muldis DB forms the sole public interface for Genezzo 
    6666after its conversion to use it, or whether Genezzo would retain alternate 
    67 public APIs that work without Muldis::DB being present on the system.  If 
    68 Muldis::DB is Genezzo's sole or primary interface, then simply C<Genezzo> 
     67public APIs that work without Muldis DB being present on the system.  If 
     68Muldis DB is Genezzo's sole or primary interface, then simply C<Genezzo> 
    6969is probably best for branding. 
    7070 
    71 =item C<Muldis::DB::Literal::Refactor(|::\w+)> 
    72  
    73 Utility modules that take Muldis::DB AST node objects as input and derive 
    74 other nodes as output, such as with the purpose of refactoring them into 
    75 canonical representations (such that users can then perform node value 
    76 equality tests for potentially any type of node), or forms that are more 
    77 efficient for particular uses but are still logically equivalent. 
     71=item C<Muldis::DB::PHMD::Refactor(|::\w+)> 
     72 
     73Utility modules that take Perl Hosted Muldis D code as input and derive 
     74other PHMD code as output, such as with the purpose of refactoring them 
     75into canonical representations (such that manual code debugging or 
     76comparisons may be made easier), or forms that are more efficient for 
     77particular uses but are still logically equivalent. 
    7878 
    7979Presumably all of these would work using static analysis methods and not 
    8080actually "execute" anything, so they are independent of any particular 
    8181Engine environment.  This isn't to say that we can't separately have 
    82 modules that help implement a specific Engine and do AST optimization that 
     82modules that help implement a specific Engine and do PHMD optimization that 
    8383knows the specific needs of that Engine's implementation environment. 
    8484 
    … …  
    8686C<Canon>, or whatever authors prefer. 
    8787 
    88 =item C<Muldis::DB::Literal::YAML> and C<Muldis::DB::Literal::XML> etc 
    89  
    90 Utility modules that serialize Muldis::DB AST nodes to, or unserialize them 
     88=item C<Muldis::DB::PHMD::YAML> and C<Muldis::DB::PHMD::XML> etc 
     89 
     90Utility modules that serialize Perl Hosted Muldis D to, or unserialize it 
    9191from, logically equivalent YAML, XML, or other generic data interchange 
    9292formats.  This implementation should be native to the Muldis D language 
    … …  
    9595between Perl 5 and Perl 6. 
    9696 
     97=item C<Muldis::DB::PHMD::Translate::ConcreteMuldisD> 
     98 
     99Utility module that parses Concrete Muldis D (character strings) into Perl 
     100Hosted Muldis D (tree of Perl Arrays etc), and also that generates the 
     101former from the latter.  The 2 formats should basically have a 1:1 
     102correspondence. 
     103 
    97104=item C<Muldis::DB::Shell> 
    98105 
    99 Implementation of a command-line user application over the Muldis::DB API 
    100 that takes string-form Muldis D as input, compiles it and runs it, and 
    101 nicely formats output for user display.  This is analogous to 
    102 L<DBI::Shell>. 
    103  
    104 =item C<DBD::Muldis::DB> 
    105  
    106 A wrapper over the Muldis::DB API that makes it work as a L<DBI> driver 
     106Implementation of a command-line user application over the Muldis DB API 
     107that takes Concrete Muldis D as input, compiles it and runs it, and nicely 
     108formats output for user display.  This is analogous to L<DBI::Shell>. 
     109 
     110=item C<DBD::MuldisDB> 
     111 
     112A wrapper over the Muldis DB API that makes it work as a L<DBI> driver 
    107113module, should that be useful.  Depending on what DBI itself permits or 
    108114requires, this could take a variety of query definition formats, including 
    109 either or both of AST form or string form (most likely) Muldis D. 
    110  
    111 =item C<Muldis::DB::Literal::Translate::TutorialD> etc 
    112  
    113 Utility module that parses the B<Tutorial D> language into Muldis::DB AST 
    114 nodes, and also that generates the former from the latter.  Mainly this is 
    115 just by-the-book using the grammar published by Darwen and Date, but it 
    116 could also handle compatible extensions by other B<D> language 
     115either or both of Concrete Muldis D or (most likely) Perl Hosted Muldis D. 
     116 
     117=item C<Muldis::DB::PHMD::Translate::TutorialD> etc 
     118 
     119Utility module that parses the B<Tutorial D> language into Perl Hosted 
     120Muldis D code, and also that generates the former from the latter.  Mainly 
     121this is just by-the-book using the grammar published by Darwen and Date, 
     122but it could also handle compatible extensions by other B<D> language 
    117123implementations.  In addition, separate utility modules can be made which 
    118124translate to and from other B<D> languages that don't look like B<Tutorial 
    119125D>. 
    120126 
    121 =item C<Muldis::DB::Literal::Translate::SQL::Native> 
    122  
    123 Utility module that parses a Muldis::DB-native variant of SQL into 
    124 Muldis::DB AST nodes, and also that generates the former from the latter. 
     127=item C<Muldis::DB::PHMD::Translate::SQL::Native> 
     128 
     129Utility module that parses a Muldis DB-native variant of SQL into 
     130Perl Hosted Muldis D, and also that generates the former from the latter. 
    125131This SQL variant is essentially a cleaned up subset of the SQL:2003 
    126132standard, with some misfeatures removed, some missing features added, and 
    127133some alterations common in other SQL DBMSs substituted or added.  Or 
    128134alternately, it is like a subset of Muldis D made to look as much like SQL 
    129 as possible.  This Muldis::DB-native SQL variant always has distinct column 
     135as possible.  This Muldis DB-native SQL variant always has distinct column 
    130136names in rowsets, requires matching column names for inputs to 
    131137union/intersect/etc, never stores or results in duplicate rows, always uses 
    … …  
    137143and what actually happens to implement it. 
    138144 
    139 =item C<Muldis::DB::Literal::Translate::SQL::\w+> 
     145=item C<Muldis::DB::PHMD::Translate::SQL::\w+> 
    140146 
    141147Utility modules that parse other variants of SQL (or subsets thereof) into 
    142 Muldis::DB AST nodes, and also that generate the former from the latter. 
     148Perl Hosted Muldis D, and also that generate the former from the latter. 
    143149Examples of these variants are the actual SQL:2003 standard, and the native 
    144150dialects of each actual SQL DBMS. 
    145151 
    146 =item C<Muldis::DB::Literal::Translate::\w+> 
     152=item C<Muldis::DB::PHMD::Translate::\w+> 
    147153 
    148154Utility modules that translate data (including code and declaratives) 
    149 between representations that are Muldis::DB AST nodes and representations 
     155between representations that are Perl Hosted Muldis D and representations 
    150156that aren't, or between 2 of the latter kind while using the former kind as 
    151157an intermediate representation.  Besides the aforementioned possibilities 
    … …  
    157163=item C<Muldis::DB::Proxy::(Server|Client|\w+)> 
    158164 
    159 Implementation(s) of a generic proxy server plus client for the Muldis::DB 
    160 API, letting the normal Muldis::DB Engine and the user application reside 
    161 in separate processes.  The client module would do 
    162 C<Muldis::DB::Engine::Role> and the server would be an application or 
    163 server-extending plugin that sits on top of the Muldis::DB API.  Or 
     165Implementation(s) of a generic proxy server plus client for the Muldis DB 
     166API, letting the normal Muldis DB Engine and the user application reside 
     167in separate processes.  The client would do 
     168C<Muldis::DB::Interface> roles and the server would be an application or 
     169server-extending plugin that sits on top of the Muldis DB API.  Or 
    164170whatever implementers want to do.  This is analogous to proxying modules 
    165171for DBI or other DBMSs. 
    … …  
    167173=item C<Muldis::DB::Engine::(SQLite|Postgres|Oracle|\w+)> 
    168174 
    169 A default (but not mandatory) namespace for Muldis::DB Engines to go, that 
    170 do C<Muldis::DB::Engine::Role(|::\w+)>.  A lot of these would likely be 
    171 implemented over existing DBMSs, which results in Muldis::DB being an 
    172 alternative API for them. 
    173  
    174 =item C<DBIx::Class::Storage::Muldis::DB> etc 
    175  
    176 An alternative plug-in storage engine for DBIx::Class that uses Muldis::DB 
    177 rather than DBI.  Analogous extensions can be added to other DBI wrappers 
    178 modules such as Tangram or Rose::DB or what have you.  In either case, said 
    179 alternatives can either be bundled with the core distros of those other 
    180 modules, or separately from them, as per their authors' preferences. 
     175A default (but not mandatory) namespace for Muldis DB Engines to go, that 
     176provide the C<new_dbms> function and do the C<Muldis::DB::Interface::\w+> 
     177roles.  A lot of these would likely be implemented over existing DBMSs, 
     178which results in Muldis DB being an alternative API for them. 
     179 
     180=item C<DBIx::Class::Storage::MuldisDB> etc 
     181 
     182An alternative plug-in storage engine for L<DBIx::Class> that uses Muldis 
     183DB rather than DBI.  Analogous extensions can be added to other DBI 
     184wrappers modules such as L<Tangram> or L<Rose::DB> or what have you.  In 
     185either case, said alternatives can either be bundled with the core distros 
     186of those other modules, or separately from them, as per their authors' 
     187preferences. 
    181188 
    182189=item C<Muldis::DB::Emulator::(DBI|JDBC|OCI|\w+)> 
    183190 
    184 Emulations of other modules or APIs as wrappers over Muldis::DB.  This is 
     191Emulations of other modules or APIs as wrappers over Muldis DB.  This is 
    185192potentially the easiest way, short of the other modules themselves being 
    186 appropriately updated, to permit migration for legacy apps to Muldis::DB 
     193appropriately updated, to permit migration for legacy apps to Muldis DB 
    187194while they have the fewest actual code changes.  The emulators would likely 
    188195employ SQL translator utilities internally. 
    189196 
    190 =item C<Muldis::DBx::\w+> 
    191  
    192 Unofficial extensions to Muldis::DB could be named in this space, though it 
     197=item C<MuldisX::DB::\w+> 
     198 
     199Unofficial extensions to Muldis DB could be named in this space, though it 
    193200doesn't have to be used if prior coordination happens between developers. 
    194201 
    195202=back 
    196203 
    197 =head1 PUBLIC SOLUTIONS BUILT OVER Muldis::DB 
     204=head1 PUBLIC SOLUTIONS BUILT OVER MULDIS DB 
    198205 
    199206I<This documentation is pending.> 
    200207 
    201208These Perl 5 applications and frameworks are, perhaps, at the front of the 
    202 line to get Muldis::DB bindings: L<Jifty>, L<Catalyst>, L<Maypole>, 
     209line to get Muldis DB bindings: L<Jifty>, L<Catalyst>, L<Maypole>, 
    203210L<Bricolage>, L<RT>.  Generally speaking, the more active the development 
    204211or the more popular the project, the higher the priority to support it. 
    … …  
    236243=head1 LICENSE AND COPYRIGHT 
    237244 
    238 This file is part of the Muldis::DB framework. 
    239  
    240 Muldis::DB is Copyright © 2002-2007, Darren Duncan. 
     245This file is part of the Muldis DB framework. 
     246 
     247Muldis DB is Copyright © 2002-2007, Darren Duncan. 
    241248 
    242249See the LICENSE AND COPYRIGHT of L<Muldis::DB> for details. 

  • ext/Muldis-DB/lib/Muldis/DB/Validator.pm

    r17897 r18088  
    1818    say "#### Muldis::DB::Validator starting test of $engine_name ####"; 
    1919 
    20     # Instantiate a Muldis::DB DBMS / virtual machine. 
     20    # Instantiate a Muldis DB DBMS / virtual machine. 
    2121    my Muldis::DB::Interface::DBMS $dbms = Muldis::DB::Interface::new_dbms( 
    2222        :engine_name($engine_name), :dbms_config($dbms_config) ); 
    … …  
    3535        (Muldis::DB::Interface::DBMS $dbms!) { 
    3636 
    37     # Declare our example executable code as Muldis::DB ASTs. 
     37    # Declare our example executable code as Muldis DB ASTs. 
    3838 
    3939    my $tynm_Text = ::Muldis::DB::Literal::EntityName.new( :text<sys.type.Text> ); 
    … …  
    177177    ); 
    178178 
    179     # Declare our example literal source data sets as Muldis::DB ASTs. 
     179    # Declare our example literal source data sets as Muldis DB ASTs. 
    180180 
    181181    my $rel_def_suppliers = ::Muldis::DB::Literal::Relation.new( 
    … …  
    330330    # Run the test suite. 
    331331    Muldis::DB::Validator::main( 
    332             :engine_name('Muldis::DB::Engine::Example'), 
    333             :dbms_config({}), 
    334         ); 
     332        :engine_name('Muldis::DB::Engine::Example'), 
     333        :dbms_config({}), 
     334    ); 
    335335 
    336336    1; 
    … …  
    346346 
    347347The Muldis::DB::Validator Perl 6 module is a common comprehensive test 
    348 suite to run against all Muldis::DB Engines.  You run it against a 
    349 Muldis::DB Engine module to ensure that the Engine and/or the database 
    350 behind it implements the parts of the Muldis::DB API that your application 
     348suite to run against all Muldis DB Engines.  You run it against a 
     349Muldis DB Engine module to ensure that the Engine and/or the database 
     350behind it implements the parts of the Muldis DB API that your application 
    351351needs, and that the API is implemented correctly.  Muldis::DB::Validator is 
    352352intended to guarantee a measure of quality assurance (QA) for Muldis::DB, 
    … …  
    354354of safety. 
    355355 
    356 Alternately, if you are writing a Muldis::DB Engine module yourself, 
     356Alternately, if you are writing a Muldis DB Engine module yourself, 
    357357Muldis::DB::Validator saves you the work of having to write your own test 
    358358suite for it.  You can also be assured that if your module passes 
    … …  
    417417=head1 LICENSE AND COPYRIGHT 
    418418 
    419 This file is part of the Muldis::DB framework. 
    420  
    421 Muldis::DB is Copyright © 2002-2007, Darren Duncan. 
     419This file is part of the Muldis DB framework. 
     420 
     421Muldis DB is Copyright © 2002-2007, Darren Duncan. 
    422422 
    423423See the LICENSE AND COPYRIGHT of L<Muldis::DB> for details.