models

package module
v0.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 27, 2024 License: BSD-3-Clause Imports: 14 Imported by: 2

README

License Latest release

models

This is a Go package used to describe data models aligned with the HTML5 data types. The model can be expressed in YAML or JSON. The YAML (or JSON) data structure is patterned after the HTML5 form elements. A single model can be used to generate HTML web forms or used to validate a map that confirms to the model. In princple generators can be written to express the model in other forms, e.g. SQL.

It is important to note that is not an Object Relational Mapper (ORM). The purpose of the model package is to facilitate describing simple data models using YAML then beable to reuse the models in other Go based projects (e.g. dataset, Newt).

This Go package assumes Go version 1.23.1 or better.

Oberservation: Web forms describe a simple data structure

The models package grew out of an observation that if you can define the elements of an HTML5 web form you can also describe a simple data model or schema. The problem is HTML5 is combersum to type, read and work with. On the other hand it lends itself to expression in simpler representations.

YAML can be used to represent a web form in a clear and concise way. From that description you can extrapulate HTML and SQL Schema. You can also use it as a guide to data validation for web form submissions.

Our common use cases.

  1. Web form as YAML can be used to generate HTML web forms
  2. Web form elements can be used to inferring the SQL column type
  3. Web form as YAML is a guide to validating web form submissions

A simple example

A "guest book" model.

id: guest_book_entry
attributes:
  action: ./signbook.html
  method: POST
  x-success: ./thankyou.html
  x-failure: ./oops.html
elements:
  - id: record_id
    type: text
    pattern: [a-z0-9]+\.[a-z0-9]+
    attributes:
      name: record_id
      placeholder: A unique record id
      required: true
  - id: name
    type: text
    attributes:
      name: name
      placeholder: E.g. Doe, Jane
      required: true
  - id: message
    type: text
    attributes:
      placeholder: Please leave a message
      name: message
  - id: signed
    type: date
    attributes:
      name: signed
      required: true

This "model" describes JSON data that might look like the following.

{ 
    "record_id": "jane.doe",
    "Doe, Jane",
    "signed": "2024-09-10"
}

The model could be used to generate the web form and validate the data. It implies an SQL Scheme. The model package provides the means of working with a model and to validate the model's content. By normalizing your data elements to throse supported by HTML5 you also can easily generate the code you need (e.g. HTML form or SQL scheme).

The package doesn't provide the extrapolated forms but does provide the functions and method to make it easy to build them.

Documentation

Index

Constants

View Source 
const (
	// Version number of release
	Version = "0.0.2"

	// ReleaseDate, the date version.go was generated
	ReleaseDate = "2024-09-27"

	// ReleaseHash, the Git hash when version.go was generated
	ReleaseHash = "a68f2d7"

	LicenseText = `` /* 1524-byte string literal not displayed */

)

Variables

This section is empty.

Functions

func ElementToHTML 

func ElementToHTML(out io.Writer, cssBaseClass string, elem *Element) error

ElementToHTML renders an individual element as HTML, includes label as well as input element.

func FmtHelp 

func FmtHelp(src string, appName string, version string, releaseDate string, releaseHash string) string

FmtHelp lets you process a text block with simple curly brace markup.

func IsValidVarname added in v0.0.2 

func IsValidVarname(s string) bool

IsValidVarname tests a sting confirms it conforms to Model's naming rule.

func ModelInteractively added in v0.0.2 

func ModelInteractively(model *Model) error

func ModelToHTML 

func ModelToHTML(out io.Writer, model *Model) error

ModelToHTML takes a model and renders an input form. The form is not populated with values through that could be done easily via JavaScript and DOM calls.

func ModelToSQLiteScheme 

func ModelToSQLiteScheme(out io.Writer, model *Model) error

func ModelToYAML added in v0.0.2 

func ModelToYAML(out io.Writer, model *Model) error

ModelToYAML renders a Model struct as YAML

func SetDefaultTypes added in v0.0.2 

func SetDefaultTypes(model *Model)

func ValidateButton added in v0.0.2 

func ValidateButton(elem *Element, formValue string) bool

func ValidateCheckbox added in v0.0.2 

func ValidateCheckbox(elem *Element, formValue string) bool

ValidateCheckbox checks is the form value was provided, returns false if empty string recieved for value.

func ValidateColor added in v0.0.2 

func ValidateColor(elem *Element, formValue string) bool

ValidateColor checks to see if the value is expressed using Hexidecimal notation

func ValidateDate added in v0.0.2 

func ValidateDate(elem *Element, formValue string) bool

ValidateDate makes sure the date string conforms to YYYY-MM-DD

func ValidateDateTimeLocal added in v0.0.2 

func ValidateDateTimeLocal(elem *Element, formValue string) bool

ValidateDateTimeLocal makes sure the datetime string conforms to Spec: https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-local-date-and-time-string

func ValidateEmail added in v0.0.2 

func ValidateEmail(elem *Element, formValue string) bool

ValidateEmail parses email address to confirm it is valid

func ValidateISNI added in v0.0.2 

func ValidateISNI(elem *Element, formValue string) bool

func ValidateImage added in v0.0.2 

func ValidateImage(elem *Element, formValue string) bool

ValidateImage, if value is empty string this returns true. NOTE: this func maybe depreciated as this is not a common form element

func ValidateMonth added in v0.0.2 

func ValidateMonth(elem *Element, formValue string) bool

ValidateMonth parses the string for a year and month value, i.e. YYYY-MM style date string

func ValidateNumber added in v0.0.2 

func ValidateNumber(elem *Element, formValue string) bool

ValidateNumber implements a number validation using the json package.

func ValidateORCID added in v0.0.2 

func ValidateORCID(elem *Element, formValue string) bool

func ValidatePassword added in v0.0.2 

func ValidatePassword(elem *Element, formValue string) bool

ValidatePassword makes sure an password input element holds a single string

func ValidateRadio added in v0.0.2 

func ValidateRadio(elem *Element, formValue string) bool

func ValidateRange added in v0.0.2 

func ValidateRange(elem *Element, formValue string) bool

ValidateRange retrieves the form's value as a float64 then checks if it is in range. Min and max must befined in the attributes of the element since they are required to make the comparison. NOTE: ValidateRange isn't currently checking the step value as I don't know if the value of the input element is supposed to be an integer for real number.

func ValidateReset added in v0.0.2 

func ValidateReset(elem *Element, formValue string) bool

func ValidateSearch added in v0.0.2 

func ValidateSearch(elem *Element, formValue string) bool

func ValidateSubmit added in v0.0.2 

func ValidateSubmit(elem *Element, formValue string) bool

func ValidateTel added in v0.0.2 

func ValidateTel(elem *Element, formValue string) bool

ValidateTel validates formValue conforms to a phone number.

func ValidateText added in v0.0.2 

func ValidateText(elem *Element, formValue string) bool

ValidateText will check to see if pattern is set, if so it will evaluate the formValue against the RegExp given in Pattern.

func ValidateTextarea added in v0.0.2 

func ValidateTextarea(elem *Element, formValue string) bool

func ValidateTime added in v0.0.2 

func ValidateTime(elem *Element, formValue string) bool

ValidateTime validates the formValue is a time format

func ValidateURL added in v0.0.2 

func ValidateURL(elem *Element, formValue string) bool

ValidateURL validates a formValue is a URL

func ValidateWeek added in v0.0.2 

func ValidateWeek(elem *Element, formValue string) bool

ValidateWeek attempts to validate a week number with year, string is WW-YYYY formatted NOTE: this is a crude validation since some years have 52 weeks other 53 depending on how the days of the week line up against the year.

Also noted is this input element isn't widely support by browser so I might drop in the future.

Types

type Element 

type Element struct {
	// Type, The type of element that you want to input. It is required. Valid values are
	// checkboxes, dropdown, input, markdown and text area.
	//
	// The input type corresponds to the native input types defined for HTML 5. E.g. text, textarea,
	// email, phone, date, url, checkbox, radio, button, submit, cancel, select
	// See MDN developer docs for input, <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input>
	Type string `json:"type,required" yaml:"type,omitempty"`

	// Id for the element, except when type is set to markdown. Can only use alpha-numeric characters,
	//  -, and _. Must be unique in the form definition. If provided, the id is the canonical identifier
	//  for the field in URL query parameter prefills.
	Id string `json:"id,omitempty" yaml:"id,omitempty"`

	// Attributes, a set of key-value pairs that define the properties of the element.
	// This is a required element as it holds the "value" attribute when expressing
	// HTML content. Other commonly use attributes
	Attributes map[string]string `json:"attributes,omitempty" yaml:"attributes,omitempty"`

	// Pattern holds a validation pattern. When combined with an input type (or input type alias, e.g. orcid)
	// produces a form element that sports a specific client side validation exceptation.  This intern can be used
	// to generate appropriate validation code server side.
	Pattern string `json:"pattern,omitempty" yaml:"pattern,omitempty"`

	// Options holds a list of values and their labels used for HTML select elements in rendering their option child elements
	Options []map[string]string `json:"optoins,omitempty" yaml:"options,omitempty"`

	// IsObjectId (i.e. is the identifier of the object) used by for the modeled data.
	// It is used in calculating routes and templates where the object identifier is required.
	IsObjectId bool `json:"is_primary_id,omitempty" yaml:"is_primary_id,omitempty"`

	// Label is used when rendering an HTML form as a label element tied to the input element via the set attribute and
	// the element's id.
	Label string `json:"label,omitempty" yaml:"label,omitempty"`
	// contains filtered or unexported fields
}

Element implementes the GitHub YAML issue template syntax for an input element. The input element YAML is described at <https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema>

While the syntax most closely express how to setup an HTML representation it is equally suitable to expressing, through inference, SQL column type definitions. E.g. a bare `input` type is a `varchar`, a `textarea` is a `text` column type, an `input[type=date]` is a date column type.

func GenerateButton added in v0.0.2 

func GenerateButton() *Element

GenerateButton sets up for an HTML input type "button"

func GenerateCheckbox added in v0.0.2 

func GenerateCheckbox() *Element

GenerateCheckbox sets up for an HTML input type "checkbox"

func GenerateColor added in v0.0.2 

func GenerateColor() *Element

GenerateColor sets up for HTML input type "color"

func GenerateDate added in v0.0.2 

func GenerateDate() *Element

GenerateDate setups up for HTML date input element

func GenerateDateTimeLocal added in v0.0.2 

func GenerateDateTimeLocal() *Element

GenerateDateTimeLocal sets up for HTML input type "datetime-local"

func GenerateEmail added in v0.0.2 

func GenerateEmail() *Element

GenerateEmail sets up for HTML input type "email"

func GenerateISNI added in v0.0.2 

func GenerateISNI() *Element

GenerateISNI sets up for an HTML input type "text" with a pattern for INSI input

func GenerateImage added in v0.0.2 

func GenerateImage() *Element

GenerateImage sets up for an HTML input type "image"

func GenerateMonth added in v0.0.2 

func GenerateMonth() *Element

GenerateMonth sets up for HTML input type "month"

func GenerateNumber added in v0.0.2 

func GenerateNumber() *Element

GenerateNumber sets up for an HTML input type "number"

func GenerateORCID added in v0.0.2 

func GenerateORCID() *Element

GenerateORCID sets up for an HTML input type text using a pattern for ORCID

func GeneratePassword added in v0.0.2 

func GeneratePassword() *Element

GeneratePassword sets up for an HTML input type "password"

func GenerateRadio added in v0.0.2 

func GenerateRadio() *Element

GenerateRadio sets up for an HTML input type "radio"

func GenerateRange added in v0.0.2 

func GenerateRange() *Element

GenerateRange sets up for an HTML input "range" (defauting is min 0 to max 100, step 1)

func GenerateReset added in v0.0.2 

func GenerateReset() *Element

GenerateReset sets up for an HTML input type "reset"

func GenerateSearch added in v0.0.2 

func GenerateSearch() *Element

GenerateSearch sets up HTML input type "search"

func GenerateSubmit added in v0.0.2 

func GenerateSubmit() *Element

GenerateSubmit sets up for an HTML input type "submit"

func GenerateTel added in v0.0.2 

func GenerateTel() *Element

GenerateTel sets up for an HTML input type "tel" (i.e. telephone number).

func GenerateText added in v0.0.2 

func GenerateText() *Element

GenerateText generates an Element setup to hold an HTML text input elements

func GenerateTextarea added in v0.0.2 

func GenerateTextarea() *Element

GenerateTextarea sets up for HTML textarea input

func GenerateTime added in v0.0.2 

func GenerateTime() *Element

GenerateTime sets up for an HTML input type "time"

func GenerateURL added in v0.0.2 

func GenerateURL() *Element

GenerateURL sets up for an HTML input type "url"

func GenerateWeek added in v0.0.2 

func GenerateWeek() *Element

GenerateWeek generates an Element setup to hold an HTML week input

func NewElement 

func NewElement(elementId string) (*Element, error)

NewElement, makes sure element id is valid, populates an element as a basic input type. The new element has the attribute "name" and label set to default values.

func (*Element) Changed added in v0.0.2 

func (e *Element) Changed(state bool)

Changed sets the change state on element

func (*Element) Check 

func (e *Element) Check(buf io.Writer) bool

Check reviews an Element to make sure if is value.

func (*Element) HasChanged added in v0.0.2 

func (e *Element) HasChanged() bool

HasChanged checks to see if the Element has been changed.

type GenElementFunc added in v0.0.2 

type GenElementFunc func() *Element

GenElementFunc is a function which will generate an Element configured represent a model's supported "types"

type Model 

type Model struct {
	// Id is a required field for model, it maps to the HTML element id and name
	Id string `json:"id,required" yaml:"id"`

	// This is a Newt specifc set of attributes to place in the form element of HTML. I.e. it could
	// be form "class", "method", "action", "encoding". It is not defined in the GitHub YAML issue template syntax
	// (optional)
	Attributes map[string]string `json:"attributes,omitempty" yaml:"attributes,omitempty"`

	// Description, A description for the issue form template, which appears in the template chooser interface.
	// (required)
	Description string `json:"description,required" yaml:"description,omitempty"`

	// Elements, Definition of the input types in the form.
	// (required)
	Elements []*Element `json:"elements,required" yaml:"elements,omitempty"`

	// Title, A default title that will be pre-populated in the issue submission form.
	// (optional) only there for compatibility with GitHub YAML Issue Templates
	Title string `json:"title,omitempty" yaml:"title,omitempty"`
	// contains filtered or unexported fields
}

Model implements a data structure description inspired by GitHub YAML issue template syntax. See <https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms>

The Model structure describes the HTML elements used to form a record. It can be used in code generation and in validating POST and PUT requests in datasetd.

func NewModel 

func NewModel(modelId string) (*Model, error)

NewModel, makes sure model id is valid, populates a Model with the identifier element providing returns a *Model and error value.

func (*Model) Changed added in v0.0.2 

func (model *Model) Changed(state bool)

Changed sets the change state

func (*Model) Check 

func (model *Model) Check(buf io.Writer) bool

Check analyze the model and make sure at least one element exists and the model has a single identifier (e.g. "identifier")

func (*Model) Define added in v0.0.2 

func (model *Model) Define(typeName string, genElementFn GenElementFunc, validateFn ValidateFunc)

Define takes a model and attaches a type definition (an element generator) and validator for the named type

func (*Model) GenElementType added in v0.0.2 

func (model *Model) GenElementType(typeName string) (*Element, bool)

GenElementType takes an element type and returns an Element struct populated for that type and true or nil and false if type is not supported.

func (*Model) GetAttributeIds 

func (m *Model) GetAttributeIds() []string

GetAttributeIds returns a slice of attribute ids found in the model's .Elements

func (*Model) GetElementById 

func (m *Model) GetElementById(id string) (*Element, bool)

GetElementById returns a Element from the model's .Elements.

func (*Model) GetElementIds 

func (m *Model) GetElementIds() []string

GetElementIds returns a slice of element ids found in the model's .Elements

func (*Model) GetModelIdentifier 

func (m *Model) GetModelIdentifier() (*Element, bool)

GetModelIdentifier() returns the element which describes the model identifier. Returns the element and a boolean set to true if found.

func (*Model) HasChanges 

func (model *Model) HasChanges() bool

HasChanges checks if the model's elements have changed

func (*Model) HasElement 

func (model *Model) HasElement(elementId string) bool

HasElement checks if the model has a given element id

func (*Model) HasElementType 

func (model *Model) HasElementType(elementType string) bool

HasElementType checks if an element type matches given type.

func (*Model) InsertElement 

func (model *Model) InsertElement(pos int, element *Element) error

InsertElement will add a new element to model.Elements in the position indicated, It will also set isChanged to true on additional.

func (*Model) IsSupportedElementType added in v0.0.2 

func (model *Model) IsSupportedElementType(eType string) bool

IsSupportedElementType checks if the element type is supported by Newt, returns true if OK false is it is not

func (*Model) ModelToYAML added in v0.0.2 

func (model *Model) ModelToYAML(out io.Writer) error

ModelInteractively takes a model and interactively prompts to create a YAML model file.

func (*Model) Register 

func (model *Model) Register(name string, fn RenderFunc)

Register takes a name (string) and a RenderFunc and registers it with the model. Registered names then can be invoke by the register name.

func (*Model) RemoveElement 

func (model *Model) RemoveElement(elementId string) error

RemoveElement removes an element by id from the model.Elements

func (*Model) Render 

func (model *Model) Render(out io.Writer, name string) error

Render takes a register render io.Writer and register name envoking the function with the model.

func (*Model) ToHTML 

func (model *Model) ToHTML(out io.Writer) error

ToHTML takes a model and trys to render an HTML web form

func (*Model) ToSQLiteScheme 

func (model *Model) ToSQLiteScheme(out io.Writer) error

ToSQLiteScheme takes a model and trys to render a SQLite3 SQL create statement.

func (*Model) UpdateElement 

func (model *Model) UpdateElement(elementId string, element *Element) error

UpdateElement will update an existing element with element id will the new element.

func (*Model) Validate added in v0.0.2 

func (model *Model) Validate(formData map[string]string) bool

Validate form data expressed as map[string]string.

type Prompt added in v0.0.3 

type Prompt struct {
	// contains filtered or unexported fields
}

Prompt holds the elements need to present questions and menus to build simple conversational console interfaces

func NewPrompt added in v0.0.3 

func NewPrompt(in io.Reader, out io.Writer, eout io.Writer) *Prompt

NewPrompt creates a new prompt struct for use with the prompt methods.

``` 

prompt := NewPrompt(os.Stdin, os.Stdout, os.Stderr)

```

func (*Prompt) GetAnswer added in v0.0.3 

func (prompt *Prompt) GetAnswer(defaultAnswer string, lower bool) string

GetAnswer display a string and get a response, e.g. "Are you Happy (Y/n)?"

``` 

prompt := NewPrompt(os.Stdin, os.Stdout, os.Stderr)
fmt.Println("Are you happy (Y/n)?")
answser := prompt.GetAnswer("y", true)
if answer == "y" {
   fmt.Println("Yeah! We're happy.")
} else {
   fmt.Println("I'm sad too.")
}

```

func (*Prompt) GetAnswers added in v0.0.3 

func (prompt *Prompt) GetAnswers(defaultAnswer string, defaultValue string, lower bool) (string, string)

GetAnswers returns an answer which has an initial verb and an predicate separted by a space. E.g. "sleeping now" -> "sleeping" "now" or "sleeping at 10:00am" -> "sleeping" "at 10:00am"

``` 

prompt := NewPrompt(os.Stdin, os.Stdout, os.Stderr)
fmt.Println("Enter an action and object")
verb, object := prompt.GetAnswers("sleeping", "now", false)
fmt.Printf("Are you %q? %q?", verb, object)

```

func (*Prompt) GetDigit added in v0.0.3 

func (prompt *Prompt) GetDigit(choices []string) (int, bool)

GetDigit returns a numeric answer that is greater than or equal than zero and less than the number of choices.

The response integer is normalized to a zero based array. E.g. a user inputs the number three it is normalized to two so it aligns with the choices present.

``` 

choices := []string{
   "Vanilla",
   "Strawberry",
   "Coffee",
   "",
   "Decline ice cream",
}
prompt := NewPrompt(os.Stdin, os.Stdout, os.Stderr)
prompt.NumberedMenu("Enter number for choice", "Pick your flavor:", choices)
if x, ok := prompt.GetDigit(choices); ok {
   fmt.Printf("You selected %d\n", x)
} else {
   fmt.Printf("No selection\n")
}

```

func (*Prompt) Menu added in v0.0.3 

func (prompt *Prompt) Menu(header string, footer string, choices []string)

Menu displays header, a list of choices and footer to form a menu.

``` 

choices := []string{
   "[1] Vanilla",
   "[2] Strawberry",
   "[3] Coffee",
   "",
   "[q]uit to decline ice cream",
}
prompt := NewPrompt(os.Stdin, os.Stdout, os.Stderr)
prompt.Menu(MenuHeader, MenuFooter, choices)

```

func (*Prompt) NumberedMenu added in v0.0.3 

func (prompt *Prompt) NumberedMenu(header string, footer string, choices []string)

NumberedMenu displays header, a list of choices and footer. The choices are numbered when forming the menu. Only non-empty strings are numbered.

``` 

choices := []string{
   "Vanilla",
   "Strawberry",
   "Coffee",
   "",
   "Decline ice cream",
}
prompt := NewPrompt(os.Stdin, os.Stdout, os.Stderr)
prompt.Menu("Enter a number and press enter", "Pick your flavor:", choices)

```

func (*Prompt) SelectMenu added in v0.0.3 

func (prompt *Prompt) SelectMenu(header string, footer string, choices []string, defaultAnswer string, defaultValue string, lower bool) (string, string)

SelectMenu display a menu and return answer(s).

``` 

prompt := NewPrompt(os.Stdin, os.Stdout, os.Stderr)
choices := []string{
    "[v]anilla",
    "[c]hocolate",
    "[s]trawberry",
}
flavor, scoops := prompt.SelectMenuItem(
    "Menu: enter flavor letter and number of scoops",
    "E.g. three vanilla scoops, "c 3",
    choices, "", "", true)
fmt.Printf("You selected %q of flavor %q.\n", scoops, flavor)

```

func (*Prompt) SelectNumberedMenu added in v0.0.3 

func (prompt *Prompt) SelectNumberedMenu(header string, footer string, choices []string) (int, bool)

SelectNumberedMenu display a numbered menu and return the intereger and OK status.

``` 

prompt := NewPrompt(os.Stdin, os.Stdout, os.Stderr)
choices := []string{
    "vanilla",
    "chocolate",
    "strawberry",
    "",
    "decline ice cream",
}
i, ok := prompt.SelectMenuNumber(
    "Menu: enter flavor number",
    "E.g. 1 for vanilla",
    choices, "", "", true)
fmt.Printf("You selected %d, status %t\n", i, ok)

```

type RenderFunc 

type RenderFunc func(io.Writer, *Model) error

RenderFunc is a function thation takes an io.Writer and Model then renders the model into the io.Writer. It is used to extend the Model to support various output formats.

type ValidateFunc added in v0.0.2 

type ValidateFunc func(*Element, string) bool

ValidateFunc is a function that validates form assocaited with the Element and the string value received in the web form (value before converting to Go type).

Source Files

View all Source files

Directories

Path Synopsis
cmd
modelgen command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.