{ "content": [ { "type": "text", "text": "# DateTime::Format::Builder::Parser (perldoc)\n\n## NAME\n\nDateTime::Format::Builder::Parser - Parser creation\n\n## SYNOPSIS\n\nmy $class = 'DateTime::Format::Builder::Parser';\nmy $parser = $class->createsingleparser(%specs);\n\n## DESCRIPTION\n\nThis is a utility class for DateTime::Format::Builder that handles creation of parsers. It is to\nhere that \"Builder\" delegates most of its responsibilities.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS** (1 subsections)\n- **FINDING IMPLEMENTATIONS**\n- **WRITING A PARSER IMPLEMENTATION** (4 subsections)\n- **SEE ALSO**\n- **SUPPORT**\n- **SOURCE**\n- **AUTHORS**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "DateTime::Format::Builder::Parser", "section": "", "mode": "perldoc", "summary": "DateTime::Format::Builder::Parser - Parser creation", "synopsis": "my $class = 'DateTime::Format::Builder::Parser';\nmy $parser = $class->createsingleparser(%specs);", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "VERSION", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 3, "subsections": [] }, { "name": "DESCRIPTION", "lines": 3, "subsections": [] }, { "name": "METHODS", "lines": 54, "subsections": [ { "name": "Organizing and Creating Parsers", "lines": 73 } ] }, { "name": "FINDING IMPLEMENTATIONS", "lines": 6, "subsections": [] }, { "name": "WRITING A PARSER IMPLEMENTATION", "lines": 1, "subsections": [ { "name": "Naming your parser", "lines": 10 }, { "name": "Declaring specification arguments", "lines": 21 }, { "name": "Define createparser", "lines": 9 }, { "name": "Callbacks", "lines": 4 } ] }, { "name": "SEE ALSO", "lines": 12, "subsections": [] }, { "name": "SUPPORT", "lines": 4, "subsections": [] }, { "name": "SOURCE", "lines": 3, "subsections": [] }, { "name": "AUTHORS", "lines": 4, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 8, "subsections": [] } ], "sections": { "NAME": { "content": "DateTime::Format::Builder::Parser - Parser creation\n", "subsections": [] }, "VERSION": { "content": "version 0.83\n", "subsections": [] }, "SYNOPSIS": { "content": "my $class = 'DateTime::Format::Builder::Parser';\nmy $parser = $class->createsingleparser(%specs);\n", "subsections": [] }, "DESCRIPTION": { "content": "This is a utility class for DateTime::Format::Builder that handles creation of parsers. It is to\nhere that \"Builder\" delegates most of its responsibilities.\n", "subsections": [] }, "METHODS": { "content": "There are two sorts of methods in this class. Those used by parser implementations and those\nused by \"Builder\". It is generally unlikely the user will want to use any of them.\n\nThey are presented, grouped according to use.\n\nParameter Handling (implementations)\nThese methods allow implementations to have validation of their arguments in a standard manner\nand due to \"Parser\"'s implementation, these methods also allow \"Parser\" to determine which\nimplementation to use.\n\nCommon parameters\nThese parameters appear for all parser implementations. These are primarily documented in\nDateTime::Format::Builder.\n\n* onmatch\n\n* onfail\n\n* postprocess\n\n* preprocess\n\n* label\n\n* length\n\nlength may be a number or an arrayref of numbers indicating the length of the input. This\nlets us optimize in the case of static length input. If supplying an arrayref of numbers,\nplease keep the number of numbers to a minimum.\n\nparams\nmy $params = $self->params;\nvalidate( @, $params );\n\nReturns declared parameters and \"common\" parameters in a hashref suitable for handing to\nParams::Validate's \"validate\" function.\n\nparamsall\nmy $allparams = $self->paramsall;\n\nReturns a hash of all the valid options. Not recommended for general use.\n\nvalidparams\nPACKAGE->validparams(%params);\n\nArguments are as per Params::Validate's \"validate\" function. This method is used to declare what\nyour valid arguments are in a parser specification.\n\nwhoseparams\nmy $class = whoseparams( $key );\n\nInternal function which merely returns to which class a parameter is unique. If not unique,\nreturns \"undef\".\n", "subsections": [ { "name": "Organizing and Creating Parsers", "content": "createsingleparser\nThis takes a single specification and returns a coderef that is a parser that suits that\nspecification. This is the end of the line for all the parser creation methods. It delegates no\nfurther.\n\nIf a coderef is specified, then that coderef is immediately returned (it is assumed to be\nappropriate).\n\nThe single specification (if not a coderef) can be either a hashref or a hash. The keys and\nvalues must be as per the specification.\n\nIt is here that any arrays of callbacks are unified. It is also here that any parser\nimplementations are used. With the spec that's given, the keys are looked at and whichever\nmodule is the first to have a unique key in the spec is the one to whom the spec is given.\n\nNote: please declare a \"validparams\" argument with an uppercase letter. For example, if you're\nwriting \"DateTime::Format::Builder::Parser::Fnord\", declare a parameter called \"Fnord\".\nSimilarly, \"DTFBP::Strptime\" should have \"Strptime\" and \"DTFBP::Regex\" should have \"Regex\".\nThese latter two don't for backwards compatibility reasons.\n\nThe returned parser will return either a \"DateTime\" object or \"undef\".\n\nmergecallbacks\nProduce either undef or a single coderef from either undef, an empty array, a single coderef or\nan array of coderefs\n\ncreatemultipleparsers\nGiven the options block (as made from \"createparser\") and a list of single parser\nspecifications, this returns a coderef that returns either the resultant \"DateTime\" object or\n\"undef\".\n\nIt first sorts the specifications using \"sortparsers\" and then creates the function based on\nwhat that returned.\n\nsortparsers\nThis takes the list of specifications and sorts them while turning the specifications into\nparsers. It returns two values: the first is a hashref containing all the length based parsers.\nThe second is an array containing all the other parsers.\n\nIf any of the specs are not code or hash references, then it will call \"croak\".\n\nCode references are put directly into the 'other' array. Any hash references without *length*\nkeys are run through \"createsingleparser\" and the resultant parser is placed in the 'other'\narray.\n\nHash references with *length* keys are run through \"createsingleparser\", but the resultant\nparser is used as the value in the length hashref with the length being the key. If two or more\nparsers have the same *length* specified then an error is thrown.\n\ncreateparser\n\"createclass\" is mostly a wrapper around \"createparser\" that does loops and stuff and calls\n\"createparser\" to create the actual parsers.\n\n\"createparser\" takes the parser specifications (be they single specifications or multiple\nspecifications) and returns an anonymous coderef that is suitable for use as a method. The\ncoderef will call \"croak\" in the event of being unable to parse the single string it expects as\ninput.\n\nThe simplest input is that of a single specification, presented just as a plain hash, not a\nhashref. This is passed directly to \"createsingleparser\" with the return value from that being\nwrapped in a function that lets it \"croak\" on failure, with that wrapper being returned.\n\nIf the first argument to \"createparser\" is an arrayref, then that is taken to be an options\nblock (as per the multiple parser specification documented earlier).\n\nAny further arguments should be either hashrefs or coderefs. If the first argument after the\noptional arrayref is not a hashref or coderef then that argument and all remaining arguments are\npassed off to \"createsingleparser\" directly. If the first argument is a hashref or coderef,\nthen it and the remaining arguments are passed to \"createmultipleparsers\".\n\nThe resultant coderef from calling either of the creation methods is then wrapped in a function\nthat calls \"croak\" in event of failure or the \"DateTime\" object in event of success.\n" } ] }, "FINDING IMPLEMENTATIONS": { "content": "\"Parser\" automatically loads any parser classes in @INC.\n\nTo be loaded automatically, you must be a \"DateTime::Format::Builder::Parser::XXX\" module.\n\nTo be invisible, and not loaded, start your class with a lower class letter. These are ignored.\n", "subsections": [] }, "WRITING A PARSER IMPLEMENTATION": { "content": "", "subsections": [ { "name": "Naming your parser", "content": "Create a module and name it in the form \"DateTime::Format::Builder::Parser::XXX\" where *XXX* is\nwhatever you like, so long as it doesn't start with a lower case letter.\n\nAlternatively, call it something completely different if you don't mind the users explicitly\nloading your module.\n\nI'd recommend keeping within the \"DateTime::Format::Builder\" namespace though --- at the time of\nwriting I've not given thought to what non-auto loaded ones should be called. Any ideas, please\nemail me.\n" }, { "name": "Declaring specification arguments", "content": "Call \"> with \"Params::Validate\" style\narguments. For example:\n\nDateTime::Format::Builder::Parser->validparams(\nparams => { type => ARRAYREF },\nRegex => {\ntype => SCALARREF,\ncallbacks => {\n'is a regex' => sub { ref(shift) eq 'Regexp' }\n}\n}\n);\n\nStart one of the key names with a capital letter. Ideally that key should match the *XXX* from\nearlier. This will be used to help identify which module a parser specification should be given\nto.\n\nThe key names *onmatch*, *onfail*, *postprocess*, *preprocess*, *label* and *length* are\npredefined. You are recommended to make use of them. You may ignore *length* as \"sortparsers\"\ntakes care of that.\n" }, { "name": "Define createparser", "content": "A class method of the name \"createparser\" that does the following:\n\nIts arguments are as for a normal method (i.e. class as first argument). The other arguments are\nthe result from a call to \"Params::Validate\" according to your specification (the \"validparams\"\nearlier), i.e. a hash of argument name and value.\n\nThe return value should be a coderef that takes a date string as its first argument and returns\neither a \"DateTime\" object or \"undef\".\n" }, { "name": "Callbacks", "content": "It is preferred that you support some callbacks to your parsers. In particular, \"preprocess\",\n\"onmatch\", \"onfail\" and \"postprocess\". See the main Builder docs for the appropriate placing\nof calls to the callbacks.\n" } ] }, "SEE ALSO": { "content": "\"datetime@perl.org\" mailing list.\n\nhttp://datetime.perl.org/\n\nperl, DateTime, DateTime::Format::Builder.\n\nParams::Validate.\n\nDateTime::Format::Builder::Parser::generic, DateTime::Format::Builder::Parser::Dispatch,\nDateTime::Format::Builder::Parser::Quick, DateTime::Format::Builder::Parser::Regex,\nDateTime::Format::Builder::Parser::Strptime.\n", "subsections": [] }, "SUPPORT": { "content": "Bugs may be submitted at .\n\nI am also usually active on IRC as 'autarch' on \"irc://irc.perl.org\".\n", "subsections": [] }, "SOURCE": { "content": "The source code repository for DateTime-Format-Builder can be found at\n.\n", "subsections": [] }, "AUTHORS": { "content": "* Dave Rolsky \n\n* Iain Truskett \n", "subsections": [] }, "COPYRIGHT AND LICENSE": { "content": "This software is Copyright (c) 2020 by Dave Rolsky.\n\nThis is free software, licensed under:\n\nThe Artistic License 2.0 (GPL Compatible)\n\nThe full text of the license can be found in the LICENSE file included with this distribution.\n", "subsections": [] } } } }