Documentation
¶
Overview ¶
Package form provides functional utilities for working with HTTP form data (url.Values).
This package offers a functional approach to building and manipulating HTTP form data using lenses, endomorphisms, and monoids. It enables immutable transformations of url.Values through composable operations.
Core Concepts ¶
The package is built around several key abstractions:
- Endomorphism: A function that transforms url.Values immutably
- Lenses: Optics for focusing on specific form fields
- Monoids: For combining form transformations and values
Basic Usage ¶
Create form data by composing endomorphisms:
form := F.Pipe3(
form.Default,
form.WithValue("username")("john"),
form.WithValue("email")("john@example.com"),
form.WithValue("age")("30"),
)
Remove fields from forms:
updated := F.Pipe1(
form,
form.WithoutValue("age"),
)
Lenses ¶
The package provides two main lenses:
- AtValues: Focuses on all values of a form field ([]string)
- AtValue: Focuses on the first value of a form field (Option[string])
Use lenses to read and update form fields:
lens := form.AtValue("username")
value := lens.Get(form) // Returns Option[string]
updated := lens.Set(O.Some("jane"))(form)
Monoids ¶
Combine multiple form transformations:
transform := form.Monoid.Concat(
form.WithValue("field1")("value1"),
form.WithValue("field2")("value2"),
)
result := transform(form.Default)
Merge form values:
merged := form.ValuesMonoid.Concat(form1, form2)
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // Default is an empty url.Values that serves as the starting point // for building form data. Use this with Pipe operations to construct // forms functionally. // // Example: // form := F.Pipe2( // form.Default, // form.WithValue("key1")("value1"), // form.WithValue("key2")("value2"), // ) Default = make(url.Values) // Monoid is a Monoid for Endomorphism that allows combining multiple // form transformations into a single transformation. The identity element // is the identity function, and concatenation composes transformations. // // Example: // transform := form.Monoid.Concat( // form.WithValue("field1")("value1"), // form.WithValue("field2")("value2"), // ) // result := transform(form.Default) Monoid = ENDO.Monoid[url.Values]() // ValuesMonoid is a Monoid for url.Values that concatenates form data. // When two forms are combined, arrays of values for the same key are // concatenated using the array Semigroup. // // Example: // form1 := url.Values{"key": []string{"value1"}} // form2 := url.Values{"key": []string{"value2"}} // merged := form.ValuesMonoid.Concat(form1, form2) // // Result: url.Values{"key": []string{"value1", "value2"}} ValuesMonoid = RG.UnionMonoid[url.Values](A.Semigroup[string]()) // AtValues is a Lens that focuses on all values of a form field as a slice. // It provides access to the complete []string array for a given field name. // // Example: // lens := form.AtValues("tags") // values := lens.Get(form) // Returns Option[[]string] // updated := lens.Set(O.Some([]string{"tag1", "tag2"}))(form) AtValues = LRG.AtRecord[url.Values, []string] // AtValue is a Lens that focuses on the first value of a form field. // It returns an Option[string] representing the first value if present, // or None if the field doesn't exist or has no values. // // Example: // lens := form.AtValue("username") // value := lens.Get(form) // Returns Option[string] // updated := lens.Set(O.Some("newuser"))(form) AtValue = F.Flow2( AtValues, composeHead, ) )
Functions ¶
func WithValue ¶
func WithValue(name string) func(value string) Endomorphism
WithValue creates an Endomorphism that sets a form field to a specific value. It returns a curried function that takes the field name first, then the value, and finally returns a transformation function.
The transformation is immutable - it creates a new url.Values rather than modifying the input.
Example:
// Set a single field
form := form.WithValue("username")("john")(form.Default)
// Compose multiple fields
form := F.Pipe3(
form.Default,
form.WithValue("username")("john"),
form.WithValue("email")("john@example.com"),
form.WithValue("age")("30"),
)
Example ¶
ExampleWithValue demonstrates how to set form field values
// Create a form with a single field
form := WithValue("username")("john")(Default)
fmt.Println(form.Get("username"))
Output: john
Example (Composition) ¶
ExampleWithValue_composition demonstrates composing multiple field assignments
// Build a form with multiple fields using Pipe
form := F.Pipe3(
Default,
WithValue("username")("john"),
WithValue("email")("john@example.com"),
WithValue("age")("30"),
)
fmt.Println(form.Get("username"))
fmt.Println(form.Get("email"))
fmt.Println(form.Get("age"))
Output: john john@example.com 30
Types ¶
type Endomorphism ¶
type Endomorphism = ENDO.Endomorphism[url.Values]
Endomorphism is a function that transforms url.Values immutably. It represents a transformation from url.Values to url.Values, enabling functional composition of form modifications.
Example:
transform := form.WithValue("key")("value")
result := transform(form.Default)
func WithoutValue ¶
func WithoutValue(name string) Endomorphism
WithoutValue creates an Endomorphism that removes a form field. The transformation is immutable - it creates a new url.Values rather than modifying the input.
Example:
// Remove a field
updated := form.WithoutValue("age")(form)
// Compose with other operations
form := F.Pipe2(
existingForm,
form.WithValue("username")("john"),
form.WithoutValue("password"),
)
Example ¶
ExampleWithoutValue demonstrates clearing a form field value
// Create a form and then clear a field
form := F.Pipe2(
Default,
WithValue("username")("john"),
WithValue("password")("secret"),
)
// Clear the password field (sets it to empty array)
sanitized := WithoutValue("password")(form)
fmt.Println(sanitized.Get("username"))
fmt.Println(sanitized.Get("password"))
Output: john
Source Files