esg

package
v1.1.6 Latest Latest
Warning

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

 Go to latest Published: Aug 23, 2020 License: BSD-3-Clause Imports: 11 Imported by: 1

README

GoDoc

Package esg is the emergent stochastic generator, where tokens are generated stochastically according to rules defining the contingencies and probabilities. It can be used for generating sentences (sg as well).

Rules

There are 5 types of rules, based on how the items within the rule are selected:

  • Uniform random and random with specified probabilities.
  • Conditional items that depend on a logical expression -- use the ? before { to mark.
  • Sequential and permuted order items that iterate through the list -- use | or $ respectively.

Unconditional items are chosen at random, optionally with specified probabilities:

RuleName {
    %50 Rule2 Rule4
    %30 'token1' 'token2'
    ...
}

where Items on separate lines within each rule are orthogonal options, chosen at uniform random unless otherwise specified with a leading %pct. %pct can add up to < 100 in which case nothing is an alternative output.

Multiple elements in an item (on the same line) are resolved and emitted in order. Terminal literals are 'quoted' -- otherwise refers to another rule: error message will flag missing rules during Validate().

Conditional items are specified by the ? after the rule name:

RuleName ? {
    Rule2 || Rule3 {
        Item1
        Item2
        ...
    }
    Rule5 && Rule6 {
        ...
    }
    ...
}

The expression before the opening bracket for each item is a standard logical expression using || (or), && (and), and ! (not), along with parens, where the elements are rules or output tokens (which must be enclosed in ' ' single quotes) that could have been generated earlier in the pass -- they evaluate to true if so, and false if not.

If the whole expression evaluates to true, then it is among items chosen at random (typically only one for conditionals but could be any number).

If just one item per rule it can be put all on one line.

Repeating choices over time:

Any rule can have an optional =%p expression just before the {, which indicates the probability of repeating the same item as last time:

RuleName ? =%70 {
...

This gives the rule a 70% chance of repeating the same item, regardless of how it was chosen before. Note that this probably doesn't make a lot of sense for conditional rules as the choice last time may not satisfy the conditions this time.

States

Each Rule or Item can have an optional State expression associated with it, which will update a States map in the overall Rules if that Rule or Item fires. The States map is a simple map[string]string and is reset for every Gen pass. It is useful for annotating the underlying state of the world implied by the generated sentence, using various role-filler values, such as those given by the modifiers below. Although the Fired map can be used to recover this information, the States map and expressions can be designed to make a clean, direct state map with no ambiguity.

In the rules text file, an = prefix indicates a state-setting expression -- it can either be a full expression or get the value automatically:

  • =Name=Value -- directly sets state Name to Value
  • =Name -- sets state Name to value of Item or Rule that it is associated with. Only non-conditional Items can be used to set the value, which is the first element in the item expression -- conditionals with sub-rules must set the value explicitly.

Expressions at the start of a rule (or sub-rule), on a separate line, are associated with the rule and activate when that rule is fired (and the implicit value is the name of the rule). Expressions at the end of an Item line are associated with the Item. Put single-line sub-rule state expressions at end just before }. Any number of state expressions can be added.

Std Modifiers

Conventional modifiers, used for defining sub-rules:

  • A = Agent
    • Ao = CoAgent
  • V = Verb
  • P = Patient,
    • Pi = Instrument
    • Pc = CoPatient
  • L = Location
  • R = Adverb

See testdata/testrules.txt and sg CCN sim for example usage.

Documentation

Overview

Package esg is the emergent stochastic generator, where tokens are generated stochastically according to rules defining the contingencies and probabilities. It can be used for generating sentences (sg as well).

Rules:

There are two types of rules: * unconditional random items * conditional items.

Unconditional items are chosen at random, optionally with specified probabilities: 

RuleName {
    %50 Rule2 Rule4
    %30 'token1' 'token2'
    ...
}

where Items on separate lines within each rule are orthogonal options, chosen at uniform random unless otherwise specified with a leading %pct. %pct can add up to < 100 in which case *nothing* is an alternative output.

Multiple elements in an item (on the same line) are resolved and emitted in order. Terminal literals are 'quoted' -- otherwise refers to another rule: error message will flag missing rules.

Conditional items are specified by the ? after the rule name: 

RuleName ? {
    Rule2 || Rule3 {
        Item1
        Item2
        ...
    }
    Rule5 && Rule6 {
        ...
    }
    ...
}

The expression before the opening bracket for each item is a standard logical expression using || (or), && (and), and ! (not), along with parens, where the elements are rules that could have been generated earlier in the pass -- they evaluate to true if so, and false if not.

If the whole expression evaluates to true, then it is among items chosen at random (typically only one for conditionals but could be any number).

If just one item per rule it can be put all on one line.

States:

Each Rule or Item can have an optional State expression associated with it, which will update a `States` map in the overall Rules if that Rule or Item fires. The `States` map is a simple `map[string]string` and is reset for every Gen pass. It is useful for annotating the underlying state of the world implied by the generated sentence, using various role-filler values, such as those given by the modifiers below. Although the Fired map can be used to recover this information, the States map and expressions can be designed to make a clean, direct state map with no ambiguity.

In the rules text file, an `=` prefix indicates a state-setting expression -- it can either be a full expression or get the value automatically:

  • `=Name=Value` -- directly sets state Name to Value
  • `=Name` -- sets state Name to value of Item or Rule that it is associated with. Only non-conditional Items can be used to set the value, which is the first element in the item expression -- conditionals with sub-rules must set the value explicitly.

Expressions at the start of a rule (or sub-rule), on a separate line, are associated with the rule and activate when that rule is fired (and the implicit value is the name of the rule). Expressions at the end of an Item line are associated with the Item. Put single-line sub-rule state expressions at end just before }.

Std Modifiers:

Conventional modifiers, used for defining sub-rules: A = Agent 

Ao = Co-Agent

V = Verb P = Patient, 

Pi = Instrument
Pc = Co-Patient

L = Location R = adverb

Index

Constants

This section is empty.

Variables

View Source 
var KiT_CondEls = kit.Enums.AddEnum(CondElsN, kit.NotBitFlag, nil)
View Source 
var KiT_Elements = kit.Enums.AddEnum(ElementsN, kit.NotBitFlag, nil)
View Source 
var KiT_RuleTypes = kit.Enums.AddEnum(RuleTypesN, kit.NotBitFlag, nil)

Functions

This section is empty.

Types

type Cond 

type Cond struct {
	El    CondEls `desc:"what type of conditional element is this"`
	Rule  string  `desc:"name of rule or token to evaluate for CRule"`
	Conds Conds   `desc:"sub-conditions for SubCond"`
}

Cond is one element of a conditional

func (*Cond) String 

func (cd *Cond) String() string

String returns string rep

func (*Cond) True 

func (cd *Cond) True(rls *Rules) bool

True returns true if conditional expression is true

func (*Cond) Validate 

func (cd *Cond) Validate(rl *Rule, it *Item, rls *Rules) []error

Validate checks for errors in expression

type CondEls 

type CondEls int32

CondEls are different types of conditional elements 

const (
	// CRule means Rule is name of a rule to evaluate truth value
	CRule CondEls = iota
	And
	Or
	Not

	// SubCond is a sub-condition expression
	SubCond

	CondElsN
)

func (*CondEls) FromString 

func (i *CondEls) FromString(s string) error

func (CondEls) MarshalJSON 

func (ev CondEls) MarshalJSON() ([]byte, error)

func (CondEls) String 

func (i CondEls) String() string

func (*CondEls) UnmarshalJSON 

func (ev *CondEls) UnmarshalJSON(b []byte) error

type Conds 

type Conds []*Cond

Conds are conditionals

func (*Conds) String 

func (cs *Conds) String() string

String returns string rep

func (*Conds) True 

func (cs *Conds) True(rls *Rules) bool

True returns true if conditional expression is true

func (*Conds) Validate 

func (cs *Conds) Validate(rl *Rule, it *Item, rls *Rules) []error

Validate checks for errors in expression

type Elem 

type Elem struct {
	El    Elements `desc:"type of element: Rule, Token, or SubItems"`
	Value string   `desc:"value of the token: name of Rule or Token"`
}

Elem is one elemenent in a concrete Item: either rule or token

func (*Elem) Gen 

func (el *Elem) Gen(rl *Rule, rls *Rules)

Gen generates expression according to the element

func (*Elem) String 

func (el *Elem) String() string

String returns string rep

func (*Elem) Validate 

func (el *Elem) Validate(it *Item, rl *Rule, rls *Rules) []error

Validate checks for config errors

type Elements 

type Elements int32

Elements are different types of elements 

const (
	// RuleEl means Value is name of a rule
	RuleEl Elements = iota

	// TokenEl means Value is a token to emit
	TokenEl

	ElementsN
)

func (*Elements) FromString 

func (i *Elements) FromString(s string) error

func (Elements) MarshalJSON 

func (ev Elements) MarshalJSON() ([]byte, error)

func (Elements) String 

func (i Elements) String() string

func (*Elements) UnmarshalJSON 

func (ev *Elements) UnmarshalJSON(b []byte) error

type Item 

type Item struct {
	Prob    float32 `desc:"probability for choosing this item -- 0 if uniform random"`
	Elems   []Elem  `desc:"elements of the rule -- for non-Cond rules"`
	Cond    Conds   `desc:"conditions for this item -- specified by ?"`
	SubRule *Rule   `desc:"for conditional, this is the sub-rule that is run with sub-items"`
	State   State   `desc:"state update name=value to set for rule"`
}

Item is one item within a rule

func (*Item) CondTrue 

func (it *Item) CondTrue(rl *Rule, rls *Rules) bool

CondTrue evalutes whether the condition is true

func (*Item) Gen 

func (it *Item) Gen(rl *Rule, rls *Rules)

Gen generates expression according to the item

func (*Item) String 

func (it *Item) String() string

String returns string rep

func (*Item) Validate 

func (it *Item) Validate(rl *Rule, rls *Rules) []error

Validate checks for config errors

type Rule 

type Rule struct {
	Name    string    `desc:"name of rule"`
	Desc    string    `desc:"description / notes on rule"`
	Type    RuleTypes `desc:"type of rule -- how to choose the items"`
	Items   []*Item   `desc:"items in rule"`
	State   State     `desc:"state update for rule"`
	PrevIdx int       `desc:"previously selected item (from perspective of current rule)"`
	CurIdx  int       `desc:"current index in Items (what will be used next)"`
	RepeatP float32   `desc:"probability of repeating same item -- signaled by =%p"`
	Order   []int     `desc:"permuted order if doing that"`
}

Rule is one rule containing some number of items

func (*Rule) Gen 

func (rl *Rule) Gen(rls *Rules)

Gen generates expression according to the rule, appending output to the rls.Output array

func (*Rule) Init 

func (rl *Rule) Init()

Init initializes the rules -- only relevant for ordered rules (restarts at start)

func (*Rule) String 

func (rl *Rule) String() string

String generates string representation of rule

func (*Rule) Validate 

func (rl *Rule) Validate(rls *Rules) []error

Validate checks for config errors

type RuleTypes 

type RuleTypes int32

RuleTypes are different types of rules (i.e., how the items are selected) 

const (
	// UniformItems is the default mutually exclusive items chosen at uniform random
	UniformItems RuleTypes = iota

	// ProbItems has specific probabilities for each item
	ProbItems

	// CondItems has conditionals for each item, indicated by ?
	CondItems

	// SequentialItems progresses through items in sequential order, indicated by |
	SequentialItems

	// PermutedItems progresses through items in permuted order, indicated by $
	PermutedItems

	RuleTypesN
)

func (*RuleTypes) FromString 

func (i *RuleTypes) FromString(s string) error

func (RuleTypes) MarshalJSON 

func (ev RuleTypes) MarshalJSON() ([]byte, error)

func (RuleTypes) String 

func (i RuleTypes) String() string

func (*RuleTypes) UnmarshalJSON 

func (ev *RuleTypes) UnmarshalJSON(b []byte) error

type Rules 

type Rules struct {
	Name      string              `desc:"name of this rule collection"`
	Desc      string              `desc:"description of this rule collection"`
	Trace     bool                `desc:"if true, will print out a trace during generation"`
	Top       *Rule               `desc:"top-level rule -- this is where to start generating"`
	Map       map[string]*Rule    `desc:"map of each rule"`
	Fired     map[string]struct{} `desc:"map of names of all the rules that have fired"`
	Output    []string            `desc:"array of output strings -- appended as the rules generate output"`
	States    State               `desc:"user-defined state map optionally created during generation"`
	ParseErrs []error             `desc:"errors from parsing"`
	ParseLn   int                 `desc:"current line number during parsing"`
}

Rules is a collection of rules

func (*Rules) Add 

func (rls *Rules) Add(rl *Rule)

Adds given rule

func (*Rules) AddOutput added in v1.0.1 

func (rls *Rules) AddOutput(out string)

AddOutput adds given string to Output array

func (*Rules) AddParseErr added in v1.0.1 

func (rls *Rules) AddParseErr(msg string)

AddParseErr adds given parser error, auto including line number

func (*Rules) Gen 

func (rls *Rules) Gen() []string

Gen generates one expression according to the rules. returns the token output, which is also avail as rls.Output

func (*Rules) HasFired 

func (rls *Rules) HasFired(name string) bool

HasFired returns true if rule of given name has fired

func (*Rules) HasOutput added in v1.0.1 

func (rls *Rules) HasOutput(out string) bool

HasOutput returns true if given token is in the output string strips ' ' delimiters if present in out string

func (*Rules) Init 

func (rls *Rules) Init()

Init initializes rule order state

func (*Rules) OpenRules 

func (rls *Rules) OpenRules(fname string) []error

OpenRules reads in a text file with rules, line-by-line simple parser

func (*Rules) ParseAddItem 

func (rls *Rules) ParseAddItem(rstack []*Rule, sp []string) (*Rule, *Item)

func (*Rules) ParseConds 

func (rls *Rules) ParseConds(cds []string) Conds

func (*Rules) ParseCurRule 

func (rls *Rules) ParseCurRule(rstack []*Rule, sp []string) *Rule

func (*Rules) ParseElems 

func (rls *Rules) ParseElems(rl *Rule, it *Item, els []string)

func (*Rules) ParseState 

func (rls *Rules) ParseState(ststr string, state *State)

func (*Rules) ReadRules 

func (rls *Rules) ReadRules(r io.Reader) []error

ReadRules reads in a text file with rules, line-by-line simple parser

func (*Rules) Rule 

func (rls *Rules) Rule(name string) *Rule

Rule returns rule of given name (nil if not found)

func (*Rules) RuleTry 

func (rls *Rules) RuleTry(name string) (*Rule, error)

RuleTry returns rule of given name, and error if not found

func (*Rules) SetFired 

func (rls *Rules) SetFired(name string)

SetFired adds given rule name to map of those that fired this round

func (*Rules) String 

func (rls *Rules) String() string

String generates string representation of all rules

func (*Rules) Validate 

func (rls *Rules) Validate() []error

Validate checks for config errors

type State 

type State map[string]string

State holds the name=value state settings associated with rule or item as a string, string map

func (*State) Add 

func (ss *State) Add(name, val string)

Add adds give name, value to state

func (*State) Set 

func (ss *State) Set(rls *Rules, val string) bool

Set sets state in rules States map, using given value for any items that have empty values

func (*State) TrimQualifiers 

func (ss *State) TrimQualifiers()

TrimQualifiers removes any :X qualifiers after state values

Source Files

View all Source files

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.