Documentation
¶
Overview ¶
Package mask formats a value as somebody reads it and gives back what a program stores.
A mask is a pattern of tokens: 000.000.000-00 is eleven digits with punctuation between them. Applying it turns 12345678900 into 123.456.789-00; unmasking turns either of them back into 12345678900.
One pattern, both sides ¶
The pattern is the whole contract, and it is shared: the browser formats what somebody types with it, and the server unmasks and checks with the same value. A formatting rule written twice is a formatting rule that disagrees with itself the first time one copy is edited -- and what reaches the database when they disagree is punctuation.
So the browser sends the raw value, not the formatted one, and this package is what the server uses to decide whether that raw value fits.
What it does not do ¶
It does not validate. 000.000.000-00 accepts eleven digits, and eleven digits are not a CPF -- the check digits are arithmetic, and arithmetic about a country's documents belongs to whoever owns that domain. Complete answers whether the pattern is filled, and that is the whole of what a shape can say.
It has no opinion about locale beyond the named patterns below, which are spellings and not rules.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Alternatives ¶
type Alternatives []Pattern
Alternatives is a mask that picks by how much was typed.
One field that takes either of two shapes -- a phone number of ten digits or eleven, a document that is one kind or another -- cannot be one pattern. The shortest pattern that still holds the value is the one used, so a field grows into the longer one as somebody types rather than jumping into it.
This is the type an application reaches for when its country has two shapes for one field:
var Phone = mask.Alternatives{"(00) 0000-0000", "(00) 00000-0000"}
func (Alternatives) Apply ¶
func (a Alternatives) Apply(value string) string
Apply formats value with whichever alternative fits it.
func (Alternatives) For ¶
func (a Alternatives) For(value string) Pattern
For is the pattern that fits this value: the shortest whose capacity holds it, and the widest when none does.
The widest when none does, so a value past every alternative is still formatted rather than dropped -- the extra characters fall off the end, which is what somebody typing one too many expects to see.
func (Alternatives) Strings ¶
func (a Alternatives) Strings() []string
Strings is the alternatives as the browser reads them.
func (Alternatives) Unmask ¶
func (a Alternatives) Unmask(value string) string
Unmask gives back what a program stores.
type Pattern ¶
type Pattern string
Pattern is a mask written in tokens.
The tokens are the ones the ecosystem this borrows its vocabulary from uses, so somebody who has written a mask before writes the same string here:
0 a digit, required 9 a digit, optional # a digit, repeated to the end of the value A a letter or a digit S a letter
Every other character is written through as it stands. A pattern that needs a literal token character is not expressible, and that is the price of the vocabulary being the familiar one; a mask of literal hashes is not a thing anybody has asked for.
const ( // Date is a day as most of the world writes it. Date Pattern = "00/00/0000" // DateISO is a day as a database writes it. DateISO Pattern = "0000-00-00" // Time is hours and minutes. Time Pattern = "00:00" // TimeSeconds is hours, minutes and seconds. TimeSeconds Pattern = "00:00:00" // CreditCard is the sixteen digits most cards carry. CreditCard Pattern = "0000 0000 0000 0000" // CardExpiry is the month and year on the front of a card. CardExpiry Pattern = "00/00" // CardSecurity is the code on the back, which is three digits or four. CardSecurity Pattern = "0009" )
The patterns this package names.
They are spellings and not rules: a pattern says how many characters of what kind, with what between them, and says nothing about whether the value means anything. A shape is what a mask can carry.
None of them belongs to a country
A national document is a rule before it is a shape -- a CPF is eleven digits AND an arithmetic check, and a mask that named the first without the second would be a framework implying it validates something it cannot. The arithmetic belongs to whoever owns the document, which is the application, and so does the pattern that goes with it:
const CPF mask.Pattern = "000.000.000-00"
A pattern is a string. Naming one costs an application one line and keeps the framework from having an opinion about which countries exist.
What is named here is what has no nationality: a date is a date everywhere, and a card is sixteen digits in every country that issues one.
func (Pattern) Accepts ¶
Accepts reports whether value fits the pattern: every character it holds is one the pattern would have kept, and there are no more than the pattern takes.
Complete asks whether enough was typed; this asks whether what was typed belongs. A caller validating a submitted field wants both.
func (Pattern) Apply ¶
Apply formats value with this pattern, keeping only what the pattern accepts.
It stops at the end of either one: a value longer than the pattern loses its tail, and a pattern longer than the value is filled as far as the value goes. A trailing separator is never left dangling -- "123." is answered as "123" -- because a separator with nothing after it is punctuation somebody is about to type past, and showing it moves the caret for no reason.
Characters the pattern cannot accept are dropped rather than refused. What somebody pastes is usually the formatted value, and refusing the punctuation in it would mean refusing a paste of exactly what this would have produced.
func (Pattern) Capacity ¶
Capacity is how many characters the tokens accept, and -1 for a pattern that repeats and therefore has no end.
func (Pattern) Complete ¶
Complete reports whether value fills every required token.
Required, so a pattern whose tail is optional is complete without it: 00000-999 is complete at five characters. A repeating token needs one.
It answers about the shape and nothing else. Eleven digits are not a CPF -- the check digits are arithmetic, and this package does no arithmetic.
func (Pattern) Unmask ¶
Unmask gives back what a program stores: the characters the tokens accept, with everything the pattern writes through removed.
It is the inverse of Apply for any value Apply produced, and it is safe on a value that was never masked: unmasking twice answers the same thing as unmasking once.
Source Files