Skip to content

Commit

Permalink
Revise documentation and naming
Browse files Browse the repository at this point in the history
  • Loading branch information
Clayton Liddell committed Apr 14, 2022
1 parent b3068dc commit 62646a9
Show file tree
Hide file tree
Showing 9 changed files with 86 additions and 100 deletions.
83 changes: 33 additions & 50 deletions src/CompilationMap/MySQL.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,57 +7,40 @@
/**
* MySQL compilation map.
*
* MySQL only supports a subset of Frictionless' date format directives. If an
* unsupported directive is encountered, an UnsupportedDirectiveException will
* be thrown by the compiler.
* Date Format Directives:
*
* Date Format Mappings:
*
* | **Description** | **Frictionless** | **MySQL** |
* |--------------------------------------------|------------------|-----------|
* | Abbreviated weekday name (Sun to Sat) | %a | %a |
* | Abbreviated month name (Jan to Dec) | %b | %b |
* | Numeric month name (0 to 12) | %m | %c |
* | Numeric day of the month (01 to 31) | %d | %d |
* | Numeric day of the month (0 to 31) | %-d | %e |
* | Microseconds (000000 to 999999) | %f | %f |
* | Hour (00 to 23) | %H | %H |
* | Hour (00 to 12) | %I | %I |
* | Minutes (00 to 59) | %M or %-M | %i |
* | Day of the year (001 to 366) | %j or %-j | %j |
* | Hour (0 to 23) | %-H | %k |
* | Hour (1 to 12) | %-I | %l |
* | Month name in full (January to December) | %B | %M |
* | Month name as a numeric value (01 to 12) | %-m | %m |
* | AM or PM | %p | %p |
* | Seconds (00 to 59) | %S or %-S | %S or %s |
* | Week where Sunday is first day (00 to 53) | %U | %U |
* | Week where Monday is first day (00 to 53) | %W | %u |
* | Weekday name in full (Sunday to Saturday) | %A | %W |
* | Numeric day of week where Sun=0 and Sat=6 | %w | %w |
* | Year as a numeric, 4-digit value | %Y | %Y |
* | Year as a numeric, 2-digit value | %y | %y |
* | A literal '%' character | %% | %% |
*
* Not Supported:
*
* | **Exclusive to Frictionless** | **Frictionless** | **MySQL** |
* |--------------------------------------------|------------------|-----------|
* | Locale date/time (e.g. 09/08/13 07:06:05) | %c | |
* | Locale’s date (e.g. 09/08/13) | %x | |
* | Locale’s time (e.g. 07:06:05) | %X | |
* | UTC offset ±HHMM[SS[.ffffff]] (e.g. +0000) | %z | |
* | Time zone name (e.g. UTC) | %Z | |
*
* | **Exclusive to MySQL** | **Frictionless** | **MySQL** |
* |--------------------------------------------|------------------|-----------|
* | Numeric day of month with suffix (3rd) | | %D |
* | Time in 12 hour format (hh:mm:ss AM/PM) | | %r |
* | Time in 24 hour format (hh:mm:ss) | | %T |
* | Week where Sunday is first day (01 to 53) | | %V |
* | Week where Monday is first day (01 to 53) | | %v |
* | Year for week where Sunday is first day | | %X |
* | Year for week where Monday is first day | | %x |
* | **Description** | **MySQL** |
* |--------------------------------------------|-----------|
* | Abbreviated weekday name (Sun to Sat) | %a |
* | Abbreviated month name (Jan to Dec) | %b |
* | Numeric month name (0 to 12) | %c |
* | Numeric day of the month (01 to 31) | %d |
* | Numeric day of the month (0 to 31) | %e |
* | Microseconds (000000 to 999999) | %f |
* | Hour (00 to 23) | %H |
* | Hour (00 to 12) | %I |
* | Minutes (00 to 59) | %i |
* | Day of the year (001 to 366) | %j |
* | Hour (0 to 23) | %k |
* | Hour (1 to 12) | %l |
* | Month name in full (January to December) | %M |
* | Month name as a numeric value (01 to 12) | %m |
* | AM or PM | %p |
* | Seconds (00 to 59) | %S or %s |
* | Week where Sunday is first day (00 to 53) | %U |
* | Week where Monday is first day (00 to 53) | %u |
* | Weekday name in full (Sunday to Saturday) | %W |
* | Numeric day of week where Sun=0 and Sat=6 | %w |
* | Year as a numeric, 4-digit value | %Y |
* | Year as a numeric, 2-digit value | %y |
* | A literal '%' character | %% |
* | Numeric day of month with suffix (3rd) | %D |
* | Time in 12 hour format (hh:mm:ss AM/PM) | %r |
* | Time in 24 hour format (hh:mm:ss) | %T |
* | Week where Sunday is first day (01 to 53) | %V |
* | Week where Monday is first day (01 to 53) | %v |
* | Year for week where Sunday is first day | %X |
* | Year for week where Monday is first day | %x |
*/
class MySQL extends \ArrayObject implements CompilationMapInterface {

Expand Down
3 changes: 3 additions & 0 deletions src/Compiler.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@

/**
* Date format compiler.
*
* If an unsupported directive is encountered, an UnsupportedTokenException will
* be thrown.
*/
class Compiler implements CompilerInterface {

Expand Down
3 changes: 0 additions & 3 deletions src/Converter.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,6 @@
* The date format parser given is used to parse the input format supplied to
* `::convert()`, and the date format compiler is then used to generate the
* converted output format.
*
* The internal language used by ASTs which all parsers are supposed to convert
* input format's to is the Frictionless date format.
*/
class Converter implements ConverterInterface {

Expand Down
4 changes: 2 additions & 2 deletions src/DirectiveToken.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@
namespace PDLT;

/**
* Frictionless/Strptime date format directive token.
* Date format directive token.
*
* E.g. '%a', '%w', '%d'...
* E.g. '%a', '%w', '%d'... (strptime)
*/
class DirectiveToken extends LiteralToken implements TokenInterface {

Expand Down
68 changes: 34 additions & 34 deletions src/Grammar/Frictionless.php → src/Grammar/Strptime.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,45 +5,45 @@
use PDLT\GrammarInterface;

/**
* Frictionless date format grammar.
* Strptime date format grammar.
*
* Since Frictionless is also the format used for representing directive tokens
* Since Strptime is also the format used for representing directive tokens
* internally, the tokens' values are the same as the literals they're wrapping.
*
* Date Format Mappings:
*
* | **Description** | **Frictionless** |
* |--------------------------------------------|------------------|
* | Abbreviated weekday name (Sun to Sat) | %a |
* | Abbreviated month name (Jan to Dec) | %b |
* | Numeric month name (0 to 12) | %m |
* | Numeric day of the month (01 to 31) | %d |
* | Numeric day of the month (0 to 31) | %-d |
* | Microseconds (000000 to 999999) | %f |
* | Hour (00 to 23) | %H |
* | Hour (00 to 12) | %I |
* | Minutes (00 to 59) | %M or %-M |
* | Day of the year (001 to 366) | %j or %-j |
* | Hour (0 to 23) | %-H |
* | Hour (1 to 12) | %-I |
* | Month name in full (January to December) | %B |
* | Month name as a numeric value (01 to 12) | %-m |
* | AM or PM | %p |
* | Seconds (00 to 59) | %S or %-S |
* | Week where Sunday is first day (00 to 53) | %U |
* | Week where Monday is first day (00 to 53) | %W |
* | Weekday name in full (Sunday to Saturday) | %A |
* | Numeric day of week where Sun=0 and Sat=6 | %w |
* | Year as a numeric, 4-digit value | %Y |
* | Year as a numeric, 2-digit value | %y |
* | A literal '%' character | %% |
* | Locale date/time (e.g. 09/08/13 07:06:05) | %c |
* | Locale’s date (e.g. 09/08/13) | %x |
* | Locale’s time (e.g. 07:06:05) | %X |
* | UTC offset ±HHMM[SS[.ffffff]] (e.g. +0000) | %z |
* | Time zone name (e.g. UTC) | %Z |
* | **Description** | **Strptime** |
* |--------------------------------------------|--------------|
* | Abbreviated weekday name (Sun to Sat) | %a |
* | Abbreviated month name (Jan to Dec) | %b |
* | Numeric month name (0 to 12) | %m |
* | Numeric day of the month (01 to 31) | %d |
* | Numeric day of the month (0 to 31) | %-d |
* | Microseconds (000000 to 999999) | %f |
* | Hour (00 to 23) | %H |
* | Hour (00 to 12) | %I |
* | Minutes (00 to 59) | %M or %-M |
* | Day of the year (001 to 366) | %j or %-j |
* | Hour (0 to 23) | %-H |
* | Hour (1 to 12) | %-I |
* | Month name in full (January to December) | %B |
* | Month name as a numeric value (01 to 12) | %-m |
* | AM or PM | %p |
* | Seconds (00 to 59) | %S or %-S |
* | Week where Sunday is first day (00 to 53) | %U |
* | Week where Monday is first day (00 to 53) | %W |
* | Weekday name in full (Sunday to Saturday) | %A |
* | Numeric day of week where Sun=0 and Sat=6 | %w |
* | Year as a numeric, 4-digit value | %Y |
* | Year as a numeric, 2-digit value | %y |
* | A literal '%' character | %% |
* | Locale date/time (e.g. 09/08/13 07:06:05) | %c |
* | Locale’s date (e.g. 09/08/13) | %x |
* | Locale’s time (e.g. 07:06:05) | %X |
* | UTC offset ±HHMM[SS[.ffffff]] (e.g. +0000) | %z |
* | Time zone name (e.g. UTC) | %Z |
*/
class Frictionless extends \ArrayObject implements GrammarInterface {
class Strptime extends \ArrayObject implements GrammarInterface {

/**
* {@inheritdoc}
Expand Down Expand Up @@ -114,7 +114,7 @@ class Frictionless extends \ArrayObject implements GrammarInterface {
];

/**
* Creates a Frictionless date format grammar.
* Creates a Strptime date format grammar.
*/
public function __construct() {
parent::__construct($this->storage);
Expand Down
11 changes: 7 additions & 4 deletions src/Parser.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@

/**
* Date format parser.
*
* Use the supplied grammar to convert the supplied date format to an
* intermediary AST language with the same directive tokens as Strptime.
*/
class Parser implements ParserInterface {

Expand Down Expand Up @@ -44,10 +47,10 @@ protected function lex(string $input_format): array {
// If the current character doesn't exist in this level of the AST, we
// have no path to tokenizing this character...
if (!isset($grammar_ptr[$char])) {
// If no valid AST character was found mid-token, the given frictionless
// format is invalid, and an exception should be thrown.
// If no valid AST character was found mid-token, the given format is
// invalid, and an exception should be thrown.
if (strlen($literal) > 1) {
throw new UnknownTokenException(sprintf('Invalid frictionless format provided; unknown token "%s".', $literal));
throw new UnknownTokenException(sprintf('Invalid format provided; token "%s" not found in grammar "%s".', $literal, get_class($this->grammar)));
}
// Since we have no path to tokenize this character, we want to go back
// to the top level of the AST...
Expand Down Expand Up @@ -85,7 +88,7 @@ protected function lex(string $input_format): array {
* Generate an Abstract Syntax Tree (AST) from the given date format.
*
* @param string $input
* Frictionless date format.
* Input date format.
*
* @return array
* Generated AST.
Expand Down
2 changes: 1 addition & 1 deletion src/UnknownTokenException.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
namespace PDLT;

/**
* Exception thrown when an invalid Frictionless date format token is found.
* Exception thrown when an invalid date format token is found.
*/
class UnknownTokenException extends \UnexpectedValueException {

Expand Down
2 changes: 1 addition & 1 deletion src/UnsupportedTokenException.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
namespace PDLT;

/**
* Exception thrown when an unsupported Frictionless date format token is found.
* Exception thrown when an unsupported date format token is found.
*/
class UnsupportedTokenException extends \UnexpectedValueException {

Expand Down
10 changes: 5 additions & 5 deletions tests/ConverterTest.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
use PDLT\Converter;
use PDLT\Parser;
use PDLT\Compiler;
use PDLT\Grammar\Frictionless as FrictionlessGrammar;
use PDLT\Grammar\Strptime as StrptimeGrammar;
use PDLT\CompilationMap\MySQL as MySQLCompilationMap;

use PHPUnit\Framework\TestCase;
Expand All @@ -18,12 +18,12 @@ class ConverterTest extends TestCase {
/**
* Test convert() in parent class.
*/
public function testFrictionlessToMySQLConverter() {
$grammar = new FrictionlessGrammar();
$frictionless_parser = new Parser($grammar);
public function testStrptimeToMySQLConverter() {
$grammar = new StrptimeGrammar();
$strptime_parser = new Parser($grammar);
$mysql_compilation_map = new MySQLCompilationMap();
$mysql_compiler = new Compiler($mysql_compilation_map);
$converter = new Converter($frictionless_parser, $mysql_compiler);
$converter = new Converter($strptime_parser, $mysql_compiler);

$result = $converter->convert('%Y-%m-%d');
$this->assertEquals('%Y-%c-%d', $result);
Expand Down

0 comments on commit 62646a9

Please sign in to comment.