forum

README

#Go.Forum

##Primitives for building a forum with threaded comments

This project contains some primitives that I use in building threaded forums using go.

TODO:

Tests

Documentation

Overview

Entry is the fundamental unit of a threaded discussion. An entry can represent a forum, a post, or a comment, depending on how it is annotated. There is nothing fundamentally distinct about these things, and their similarities (including hierarchical nesting) are abundant.

For entry methods that manipulate the database in some way, see entry_db.go

Entry methods and functions that access a database are placed here.

To be initialized, the forum expects a live Postgres database connection handle to be passed in. For example:

var db *sql.DB

func main() {
	db = (...get the object...)

	forum.Initialize(db)
}

This file manages all SQL queries that are made in the forum package.

Entry is the fundamental unit of a threaded discussion. An entry can represent a forum, a post, or a comment, depending on how it is annotated. There is nothing fundamentally distinct about these things, and their similarities (including hierarchical nesting) are abundant.

Index

• Constants
• Variables
• func Initialize(db *sql.DB)
• type Delta
• type Entry
  • func AncestorEntries(root int64, user User) (*Entry, error)
  • func Arrange(e *Entry) *Entry
  • func DepthOneDescendantEntries(root int64, user User) (*Entry, error)
  • func DescendantEntries(root int64, user User) (*Entry, error)
  • func New() *Entry
  • func OneEntry(id int64) (*Entry, error)
  • func (e *Entry) AddChild(newE *Entry)
  • func (e *Entry) Child() *Entry
  • func (e *Entry) ChildCount() int64
  • func (e *Entry) Less(cmp *Entry) bool
  • func (e *Entry) Parent() *Entry
  • func (e *Entry) Persist(parentId int64) error
  • func (e *Entry) Points() int64
  • func (e *Entry) Root() *Entry
  • func (e *Entry) Score() float64
  • func (e *Entry) Sibling() *Entry
• type User
• type Vote
  • func FindVote(entryId, userId int64) (*Vote, bool)
  • func (v *Vote) Persist() error

Constants

const (
	DECAY = 0.5 //Decay factor for childrens' scores
)

Variables

var Config *conf = &conf{}

Create a package-global config object holding needed globals

Functions

func Initialize

func Initialize(db *sql.DB)

Niladic function to setup the forum

Types

type Delta

type Delta struct {
	Id         int64     "Unique identifier of this delta"
	PostId     int64     "ID of the modified post"
	TitleDelta string    "Changes made to the title, if any"
	BodyDelta  string    "Changes made to the body, if any"
	Modified   time.Time "Time at which the changes were made"
	ModifierId int64     "ID of the user who modified the post"
}

type Entry

type Entry struct {
	Id       int64     //The ID of the post
	Title    string    //Title of the post. Will be empty for entries that are really intended to be comments.
	Body     string    //Contents of the post. Will be empty for entries that are intended to be links.
	Created  time.Time //Time at which the post was created.
	AuthorId int64     `schema:"-"` //ID of the author of the post
	Forum    bool      `schema:"-"` //Is this Entry actually a forum instead?
	Url      bool      `schema:"-"` //Is this Entry just a link?

	AuthorHandle string  //Name of the author
	Seconds      float64 //Seconds since creation
	Upvotes      int64
	Downvotes    int64
	ParentId     int64 //ID of the parent of this post, if any

	UserVote *Vote //A Vote representing how the current user has voted on this Entry
	// contains filtered or unexported fields
}

Put ModifiedBy, ModifiedAuthor in a separate table. A post can only be created once but modified an infinite number of times.

func AncestorEntries

func AncestorEntries(root int64, user User) (*Entry, error)

func Arrange

func Arrange(e *Entry) *Entry

Return an ordered *Entry tree Order among siblings is determined by Score Score is determined recursively, with all Child (and Child's Siblings, their children, etc) contributing to the score

func DepthOneDescendantEntries

func DepthOneDescendantEntries(root int64, user User) (*Entry, error)

Retrieves entries that are immediate descendants of the ancestral entry, including the ancestral entry itself

func DescendantEntries

func DescendantEntries(root int64, user User) (*Entry, error)

Retrieves all entries that are descendants of the ancestral entry, including the ancestral entry itself

func New

func New() *Entry

func OneEntry

func OneEntry(id int64) (*Entry, error)

Retrieve one entry by its ID, if it exists. Error if not.

func (*Entry) AddChild

func (e *Entry) AddChild(newE *Entry)

Add a child node to the current entry If the current entry's child slot is full, recursively try the child's sibling(s)' slots until an open (nil) slot is found

func (*Entry) Child

func (e *Entry) Child() *Entry

func (*Entry) ChildCount

func (e *Entry) ChildCount() int64

func (*Entry) Less

func (e *Entry) Less(cmp *Entry) bool

func (*Entry) Parent

func (e *Entry) Parent() *Entry

func (*Entry) Persist

func (e *Entry) Persist(parentId int64) error

Stores an entry to the database and correctly builds its ancestry based on its parent's ID.

func (*Entry) Points

func (e *Entry) Points() int64

Points return a user-visible indicator of Upvotes - Downvotes

func (*Entry) Root

func (e *Entry) Root() *Entry

Returns the root of a tree

func (*Entry) Score

func (e *Entry) Score() float64

Score determines sort order and can also be shown to help explain why comments are in their given order

func (*Entry) Sibling

func (e *Entry) Sibling() *Entry

type User

type User interface {
	GetId() int64
}

type Vote

type Vote struct {
	//Id       int64     //The ID of this vote
	EntryId  int64     //The ID of the post
	UserId   int64     //The ID of the user who cast this vote
	Upvote   bool      //Is this an upvote?
	Downvote bool      //Is this a downvote?
	Created  time.Time //Time at which the vote was cast
}

func FindVote

func FindVote(entryId, userId int64) (*Vote, bool)

Retrieve one vote based on entry ID and user ID.

func (*Vote) Persist

func (v *Vote) Persist() error

Stores an entry to the database and correctly builds its ancestry based on its parent's ID.