<commit_before>package main

import (
	"errors"
	"fmt"
	"io"
	"io/ioutil"
	"net"
	"os"
	"os/exec"
	"strconv"
	"strings"

	"github.com/google/gops/internal"
	"github.com/google/gops/signal"
)

var cmds = map[string](func(addr net.TCPAddr) error){
	"stack":      stackTrace,
	"gc":         gc,
	"memstats":   memStats,
	"version":    version,
	"pprof-heap": pprofHeap,
	"pprof-cpu":  pprofCPU,
	"stats":      stats,
	"trace":      trace,
}

func stackTrace(addr net.TCPAddr) error {
	return cmdWithPrint(addr, signal.StackTrace)
}

func gc(addr net.TCPAddr) error {
	_, err := cmd(addr, signal.GC)
	return err
}

func memStats(addr net.TCPAddr) error {
	return cmdWithPrint(addr, signal.MemStats)
}

func version(addr net.TCPAddr) error {
	return cmdWithPrint(addr, signal.Version)
}

func pprofHeap(addr net.TCPAddr) error {
	return pprof(addr, signal.HeapProfile)
}

func pprofCPU(addr net.TCPAddr) error {
	fmt.Println("Profiling CPU now, will take 30 secs...")
	return pprof(addr, signal.CPUProfile)
}

func trace(addr net.TCPAddr) error {
	fmt.Println("Tracing now, will take 5 secs...")
	out, err := cmd(addr, signal.Trace)
	if err != nil {
		return err
	}
	if len(out) == 0 {
		return errors.New("nothing has traced")
	}
	tmpfile, err := ioutil.TempFile("", "trace")
	if err != nil {
		return err
	}
	defer os.Remove(tmpfile.Name())
	if err := ioutil.WriteFile(tmpfile.Name(), out, 0); err != nil {
		return err
	}
	cmd := exec.Command("go", "tool", "trace", tmpfile.Name())
	cmd.Env = os.Environ()
	cmd.Stdin = os.Stdin
	cmd.Stdout = os.Stdout
	cmd.Stderr = os.Stderr
	return cmd.Run()
}

func pprof(addr net.TCPAddr, p byte) error {

	tmpDumpFile, err := ioutil.TempFile("", "profile")
	if err != nil {
		return err
	}
	{
		out, err := cmd(addr, p)
		if err != nil {
			return err
		}
		if len(out) == 0 {
			return errors.New("failed to read the profile")
		}
		defer os.Remove(tmpDumpFile.Name())
		if err := ioutil.WriteFile(tmpDumpFile.Name(), out, 0); err != nil {
			return err
		}
	}
	// Download running binary
	tmpBinFile, err := ioutil.TempFile("", "binary")
	if err != nil {
		return err
	}
	{
		out, err := cmd(addr, signal.BinaryDump)
		if err != nil {
			return fmt.Errorf("failed to read the binary: %v", err)
		}
		if len(out) == 0 {
			return errors.New("failed to read the binary")
		}
		defer os.Remove(tmpBinFile.Name())
		if err := ioutil.WriteFile(tmpBinFile.Name(), out, 0); err != nil {
			return err
		}
	}
	cmd := exec.Command("go", "tool", "pprof", tmpBinFile.Name(), tmpDumpFile.Name())
	cmd.Env = os.Environ()
	cmd.Stdin = os.Stdin
	cmd.Stdout = os.Stdout
	cmd.Stderr = os.Stderr
	return cmd.Run()
}

func stats(addr net.TCPAddr) error {
	return cmdWithPrint(addr, signal.Stats)
}

func cmdWithPrint(addr net.TCPAddr, c byte) error {
	out, err := cmd(addr, c)
	if err != nil {
		return err
	}
	fmt.Printf("%s", out)
	return nil
}

// targetToAddr tries to parse the target string, be it remote host:port
// or local process's PID.
func targetToAddr(target string) (*net.TCPAddr, error) {
	if strings.Index(target, ":") != -1 {
		// addr host:port passed
		var err error
		addr, err := net.ResolveTCPAddr("tcp", target)
		if err != nil {
			return nil, fmt.Errorf("couldn't parse dst address: %v", err)
		}
		return addr, nil
	}
	// try to find port by pid then, connect to local
	pid, err := strconv.Atoi(target)
	if err != nil {
		return nil, fmt.Errorf("couldn't parse PID: %v", err)
	}
	port, err := internal.GetPort(pid)
	addr, _ := net.ResolveTCPAddr("tcp", "127.0.0.1:"+port)
	return addr, nil
}

func cmd(addr net.TCPAddr, c byte) ([]byte, error) {
	conn, err := cmdLazy(addr, c)
	if err != nil {
		return nil, fmt.Errorf("couldn't get port by PID: %v", err)
	}

	all, err := ioutil.ReadAll(conn)
	if err != nil {
		return nil, err
	}
	return all, nil
}

func cmdLazy(addr net.TCPAddr, c byte) (io.Reader, error) {
	conn, err := net.DialTCP("tcp", nil, &addr)
	if err != nil {
		return nil, err
	}
	if _, err := conn.Write([]byte{c}); err != nil {
		return nil, err
	}
	return conn, nil
}
<commit_msg>Print filenames on client for pprof and trace dumps (#38)<commit_after>package main

import (
	"errors"
	"fmt"
	"io"
	"io/ioutil"
	"net"
	"os"
	"os/exec"
	"strconv"
	"strings"

	"github.com/google/gops/internal"
	"github.com/google/gops/signal"
)

var cmds = map[string](func(addr net.TCPAddr) error){
	"stack":      stackTrace,
	"gc":         gc,
	"memstats":   memStats,
	"version":    version,
	"pprof-heap": pprofHeap,
	"pprof-cpu":  pprofCPU,
	"stats":      stats,
	"trace":      trace,
}

func stackTrace(addr net.TCPAddr) error {
	return cmdWithPrint(addr, signal.StackTrace)
}

func gc(addr net.TCPAddr) error {
	_, err := cmd(addr, signal.GC)
	return err
}

func memStats(addr net.TCPAddr) error {
	return cmdWithPrint(addr, signal.MemStats)
}

func version(addr net.TCPAddr) error {
	return cmdWithPrint(addr, signal.Version)
}

func pprofHeap(addr net.TCPAddr) error {
	return pprof(addr, signal.HeapProfile)
}

func pprofCPU(addr net.TCPAddr) error {
	fmt.Println("Profiling CPU now, will take 30 secs...")
	return pprof(addr, signal.CPUProfile)
}

func trace(addr net.TCPAddr) error {
	fmt.Println("Tracing now, will take 5 secs...")
	out, err := cmd(addr, signal.Trace)
	if err != nil {
		return err
	}
	if len(out) == 0 {
		return errors.New("nothing has traced")
	}
	tmpfile, err := ioutil.TempFile("", "trace")
	if err != nil {
		return err
	}
	defer os.Remove(tmpfile.Name())
	if err := ioutil.WriteFile(tmpfile.Name(), out, 0); err != nil {
		return err
	}
	fmt.Printf("Trace dump saved to: %s\n", tmpfile.Name())
	cmd := exec.Command("go", "tool", "trace", tmpfile.Name())
	cmd.Env = os.Environ()
	cmd.Stdin = os.Stdin
	cmd.Stdout = os.Stdout
	cmd.Stderr = os.Stderr
	return cmd.Run()
}

func pprof(addr net.TCPAddr, p byte) error {

	tmpDumpFile, err := ioutil.TempFile("", "profile")
	if err != nil {
		return err
	}
	{
		out, err := cmd(addr, p)
		if err != nil {
			return err
		}
		if len(out) == 0 {
			return errors.New("failed to read the profile")
		}
		defer os.Remove(tmpDumpFile.Name())
		if err := ioutil.WriteFile(tmpDumpFile.Name(), out, 0); err != nil {
			return err
		}
	}
	// Download running binary
	tmpBinFile, err := ioutil.TempFile("", "binary")
	if err != nil {
		return err
	}
	{
		out, err := cmd(addr, signal.BinaryDump)
		if err != nil {
			return fmt.Errorf("failed to read the binary: %v", err)
		}
		if len(out) == 0 {
			return errors.New("failed to read the binary")
		}
		defer os.Remove(tmpBinFile.Name())
		if err := ioutil.WriteFile(tmpBinFile.Name(), out, 0); err != nil {
			return err
		}
	}
	fmt.Printf("Profiling dump saved to: %s\n", tmpDumpFile.Name())
	fmt.Printf("Binary file saved to: %s\n", tmpBinFile.Name())
	cmd := exec.Command("go", "tool", "pprof", tmpBinFile.Name(), tmpDumpFile.Name())
	cmd.Env = os.Environ()
	cmd.Stdin = os.Stdin
	cmd.Stdout = os.Stdout
	cmd.Stderr = os.Stderr
	return cmd.Run()
}

func stats(addr net.TCPAddr) error {
	return cmdWithPrint(addr, signal.Stats)
}

func cmdWithPrint(addr net.TCPAddr, c byte) error {
	out, err := cmd(addr, c)
	if err != nil {
		return err
	}
	fmt.Printf("%s", out)
	return nil
}

// targetToAddr tries to parse the target string, be it remote host:port
// or local process's PID.
func targetToAddr(target string) (*net.TCPAddr, error) {
	if strings.Index(target, ":") != -1 {
		// addr host:port passed
		var err error
		addr, err := net.ResolveTCPAddr("tcp", target)
		if err != nil {
			return nil, fmt.Errorf("couldn't parse dst address: %v", err)
		}
		return addr, nil
	}
	// try to find port by pid then, connect to local
	pid, err := strconv.Atoi(target)
	if err != nil {
		return nil, fmt.Errorf("couldn't parse PID: %v", err)
	}
	port, err := internal.GetPort(pid)
	addr, _ := net.ResolveTCPAddr("tcp", "127.0.0.1:"+port)
	return addr, nil
}

func cmd(addr net.TCPAddr, c byte) ([]byte, error) {
	conn, err := cmdLazy(addr, c)
	if err != nil {
		return nil, fmt.Errorf("couldn't get port by PID: %v", err)
	}

	all, err := ioutil.ReadAll(conn)
	if err != nil {
		return nil, err
	}
	return all, nil
}

func cmdLazy(addr net.TCPAddr, c byte) (io.Reader, error) {
	conn, err := net.DialTCP("tcp", nil, &addr)
	if err != nil {
		return nil, err
	}
	if _, err := conn.Write([]byte{c}); err != nil {
		return nil, err
	}
	return conn, nil
}
<|endoftext|>


<commit_before>//
// BUILD INSTRUCTIONS:
//     go build cpm.go
//
// RUN INSTRUCTIONS:
//     go cpm
//
// PARAMETERS:
// If you want to change the clique size (k), simply change the k
// variable in the main and recompile. I did not have time to make k
// a command line argument.
//
// THEORY OF OPERATION
//    1- first find all cliques of size k in the graph
//    2- then create graph where nodes are cliques of size k
//    3- add edges if two nodes (cliques) share k-1 common nodes
//    4- each connected component is a community
//
// MODEL GRAPH
// Below is the graph that I used for a model while developing the
// clique percolation method (CPM) module. It is sometimes
// referenced in the comments as the Model Graph in order to make
// things more clear. This is the graph that is built up in the main
// function, but obviously the code should work with any graph.
//
//
//   +----+           +----+
//   | v2 |-----------| v1 |
//   +----++        +-+----+
//         |        |
//         |        |
//         +-+----+-+
//     +-----| v3 |------+
//     |     +----+      |
//     |                 |
//     |                 |
//     |                 |
//  +----+            +----+
//  | v4 |------------| v5 |
//  +--+-+     +------+-+--+
//     | |     |        |
//     | +-----+--------++
//     |       |        ||
//     |       |        ||
//  +--+-+-----+      +-+--+
//  | v6 |------------| v7 |
//  +----+            +----+
//     |                 |
//     +----+    +-------+
//          +----+
//          | v8 |
//        +-+----++
//        |       |
//        |       |
// +----+-+       +-+----+
// | v9 |-----------|v10 |
// +----+           +----+
//

package main

import "fmt"
import "strconv"

type GraphNode struct {
    label string  // any string, but in our model case (v1, v2, ..., v10)
    neighbors []*GraphNode // records edges from this node.
    associated_clique *Clique // required when building community
                              // graph; not required for starting
                              // graph
}

type CliqueCandidate struct {
    nodes []*GraphNode
    next *CliqueCandidate
}

type Clique struct {
    nodes []*GraphNode
    next *Clique
}

// FUNCTION: NewGraphNode
//
// DESCRIPTION: Creates a new graph node. The assoc_clique is
// required when building the community graph. Each k-clique is
// recorded as a node in the community graph. To determine whether
// or not an edge should be created between nodes in the community
// graph, we must determine if that they have k-1 nodes (vertices)
// in common. This is easier to do when there is a mapping between
// the community node and the clique that caused the node to be
// created. The clique contains a list of vertices.

func NewGraphNode (label string, assoc_clique *Clique) *GraphNode {
    new_node := new(GraphNode)
    new_node.label = label
    new_node.associated_clique = assoc_clique
    return new_node
}

// FUNCTION: AddNeighbor
//
// DESCRIPTION: Adds a neighboring vertex to the graph node's
// neighbor list because there is an edge connecting gn and n.

func (gn *GraphNode) AddNeighbor (n *GraphNode) {
    gn.neighbors = append(gn.neighbors, n)
}

// FUNCTION: PrintGraph
//
// DESCRIPTION: Prints a graph -- vertices and edges.

func PrintGraph(g []*GraphNode) {
    if g == nil {
        fmt.Printf("empty graph\n")
    }
    for _, e := range g {
        fmt.Printf("%s:  ", e.label)
        glen := len(g)
        if glen > 0 {
            for _, n := range e.neighbors {
                fmt.Printf("%s ", n.label)
            }
        }
        fmt.Printf("\n")
    }
}

// FUNCTION: GetCliqueCandidates
//
// PARAMETERS:
// - k int
// - node_list []*GraphNode
//
// DESCRIPTION: A recursive function that generates all the node
// permutations that could form a k-clique for a given
// node. node_list is essentially the neighbor list for some
// node. For example, lets say we want to generate a candidate list
// for v5 with k=3. The original node_list would be {v3, v4, v6, v7}
// (all of v5's neighbors). We remove the first node, v3, and then
// recursive call GetCliqueCandates with node_list = {v4, v6,
// v7}. Again, we remove the first node, v4, and recursively call
// with node_list equal to {v6, v7}. This is our anchor case because
// k=3 and we will add v5 later to this canidate list, thus giving
// us a {v5, v6, v7} candidate clique. When the recursive call
// begins to unwind, we add the removed node in each slot of the
// candidate list. For example, on the first unwind, we start with a
// removed node of v4 and clique_list of {v6, v7}. v4 is substitued
// for each element and this yields a clique_list of {v6, v7}, {v4,
// v7}, and {v6, v4}. And this continues recursively. For v3, we
// would then get a clique_list of:
//
//              {v6, v7}
//              {v4, v7}
//              {v6, v4}
//              {v3, v7}
//              {v6, v3}
//              {v3, v7}  -- duplicate, not added
//              {v4, v3}
//              {v3, v4}  -- duplicate, not added
//              {v6, v3}  -- duplicate, not added
//
// When the function returns, the caller can then make the final candidate
// list using the examination node (v5 in our example). This will yield
// a candidate clique list of:
//
//              {v5, v6, v7}
//              {v5, v4, v7}
//              {v5, v6, v4}
//              {v5, v3, v7}
//              {v5, v6, v3}
//              {v5, v4, v3}
//
//
func GetCliqueCandidates (k int, node_list []*GraphNode) *CliqueCandidate {

    if k < 2 {
        return nil
    }
    if len(node_list) < k - 1 {
        return nil
    }
    if len(node_list) == k - 1 {
        new_candidate := new (CliqueCandidate)
        new_candidate.nodes = node_list
        new_candidate.next = nil
        return new_candidate
    }

    node := node_list[0] // the removed node
    clique_list := GetCliqueCandidates(k, node_list[1:])
    var return_clique_list *CliqueCandidate = clique_list

    for item := clique_list; item != nil; item = item.next {
        for i, _ := range item.nodes {
            new_candidate := new (CliqueCandidate)
            new_candidate.nodes = make([]*GraphNode, len(item.nodes), len(item.nodes))
            for k, v := range item.nodes {
                new_candidate.nodes[k] = v
            }
            // new_candidate.nodes = item.nodes // copies array
            new_candidate.nodes[i] = node

            // only add this candidate list if doesn't already exist
            if new_candidate.IsDuplicate(return_clique_list) == false {

                new_candidate.next = return_clique_list
                return_clique_list = new_candidate
            }
        }
    }

    return return_clique_list
}

// FUNCTION: MakeCliqueList
//
// PARAMETERS:
//
// - candidate_list *CliqueCandidate
// - examination_node *GraphNode
//
// DESCRIPTION: Determines if nodes on the candidate list are
// completely connected. If the nodes are completely connected, then
// it creates a clique, which includes all candidates and the
// examination node and places them on the clique list to be returned.
//
// For example, the following candidates would be generated for node
// v5 in the Model Graph for a k = 3 clique, and this is what is
// essentially returned from GetCliqueCandidates:
//
//     - v6 v7
//     - v4 v7
//     - v6 v4
//     - v3 v4
//     - v6 v3
//     - v3 v7
//
// These are just candidates to form a clique (k=3) with
// v5. MakeCliqueList determines whether the above nodes do form a
// clique with v5, and if they do then MakeCliqueList places a
// Clique node on the return list. Here's what the determination should be
// for the above candidates:
//
//     - v6 v7  - yes, forms k=3 clique with v5
//     - v4 v7  - yes  "
//     - v6 v4  - yes  "
//     - v3 v4  - yes  "
//     - v6 v3  - no, does not form k=3 clique with v5
//     - v3 v7  - no, "
//
// So, the return clique list should look like the following in the
// case of examination node v5 and the above candidate list:
//
//     +---------------------+     +--+--+--+
//     |nodes []*GraphNodes--+---->|v5|v6|v7|
//     |next *Clique         |     +--+--+--+
//     |           |         |
//     +-----------+---------+
//                 |
//                 v
//     +---------------------+     +--+--+--+
//     |nodes []*GraphNodes--+---->|v5|v4|v7|
//     |next *Clique         |     +--+--+--+
//     |           |         |
//     +-----------+---------+
//                 |
//                 v
//     +---------------------+     +--+--+--+
//     |nodes []*GraphNodes--+---->|v5|v6|v4|
//     |next *Clique         |     +--+--+--+
//     |           |         |
//     +-----------+---------+
//                 |
//                 v
//     +---------------------+     +--+--+--+
//     |nodes []*GraphNodes--+---->|v5|v4|v3|
//     |next *Clique         |     +--+--+--+
//     |           |         |
//     +-----------+---------+
//                 |
//                 v
//              +----+
//              |nil |
//              +----+
//
//
func (candidate_list *CliqueCandidate) MakeCliqueList(
    examination_node *GraphNode) *Clique {

    var clique_list *Clique = nil

    for item := candidate_list; item != nil; item = item.next {
        candidate_list_is_clique := true // assumed, not yet determined
        item_nodes_len := len(item.nodes)
        for i := 0; i < item_nodes_len && candidate_list_is_clique; i++ {
            candidate_node := item.nodes[i]
            for j := i + 1; j < item_nodes_len; j++ {
                // if the candidate node is not connected to all other
                // nodes then this candidate does not form clique
                if candidate_node.IsConnected(item.nodes[j]) == false {
                    candidate_list_is_clique = false
                    break
                }
            }
        }
        if (candidate_list_is_clique == true) {
            new_clique := new (Clique)
            new_clique.nodes = make ([]*GraphNode,
                item_nodes_len + 1,
                item_nodes_len + 1)
            copy (new_clique.nodes, item.nodes)
            new_clique.nodes[item_nodes_len] = examination_node
            new_clique.next = clique_list
            clique_list = new_clique
        }
    }
    return clique_list
}

// FUNCTION: IsConnected
//
// DESCRIPTION: Determines if the candidate node (cn) is connected to
// some node (sn)

func (cn *GraphNode) IsConnected (sn *GraphNode) bool {
    is_connected := false
    for _,item := range sn.neighbors {
        if item == cn {
            is_connected = true
            break
        }
    }
    return is_connected
}

// FUNCTION: IsDuplicate
//
// DESCRIPTION: After examining each node, we will have many
// different duplicate clique candidates (i.e., candidates that all
// have the same vertices). We need to create a candidate list that
// has no duplicates and IsDuplicate determines that.

func (cc *CliqueCandidate) IsDuplicate (clist *CliqueCandidate) bool {
    return_val := false

    for item := clist; item != nil; item = item.next {
        match_count := len (cc.nodes)
        for _, ccnode := range cc.nodes {
            for _, list_node := range item.nodes {
                if (list_node == ccnode) {
                    match_count--
                    if match_count == 0 {
                        return true // duplicate list found
                    }
                    break
                }
            }
        }
    }

    return return_val
}

// FUNCTION: NotRecorded
//
// DESCRIPTION: Determines whether nor not the clique is already on
// the clique_list. When we merge the candidate lists for each node,
// we will invariably find duplicates, but we only want one unique
// clique recorded -- not multiples.

func (clique *Clique) NotRecorded (clique_list *Clique) bool {

    for item := clique_list; item != nil; item = item.next {
        match_count := len(item.nodes)
        if match_count != len(clique.nodes) {
            continue
        }
        for _, node := range item.nodes {
            for _, exam_node := range clique.nodes {
                if exam_node == node {
                    match_count--
                    if match_count == 0 {
                        return false
                    }
                }
            }
        }
    }
    return true
}

// FUNCTION: AppendClique
//
// DESCRIPTION: Appends src_clique_list to dest_clique_list. Returns
// dest_clique_list
//
func AppendClique (dest_clique_list *Clique,
    src_clique_list *Clique) (*Clique) {

        if dest_clique_list == nil {
            return nil
        }

        var last_item *Clique
        for last_item = dest_clique_list;
            last_item.next != nil;
            last_item = last_item.next {
            }

        for clique := src_clique_list; clique != nil; clique = clique.next {
            if clique.NotRecorded(dest_clique_list) == true {
                new_clique := new(Clique)
                new_clique.nodes = clique.nodes
                new_clique.next = nil
                last_item.next = new_clique
                last_item = new_clique
            }
        }
        return dest_clique_list
}

// FUNCTION: CreateLabel
//
// DESCRIPTION: Generates a label for a node in the community
// graph. It does this by concatening the labels of each vertex from
// the origial graph that is in a clique to a single label name.

func CreateLabel (nodes []*GraphNode) string {
    var new_label string
    for i,item := range nodes {
        if i == 0 {
            new_label = item.label
        } else {
            new_label += "," + item.label
        }
    }
    return new_label
}

// FUNCTION: Kminu1CommonNodes
//
// DESCRIPTION: Determines if two nodes on the newly created
// community graph share k-1 vertices from the original graph. If
// so, then there should be an edge from gn and node in the
// community graph.

func (gn *GraphNode) Kminus1CommonNodes (node *GraphNode, k int) bool {
    common_node_count := 0
    return_value := false

    for _, exam_node := range gn.associated_clique.nodes {
        for _, common_node := range node.associated_clique.nodes {
            if exam_node == common_node {
                common_node_count++
                if common_node_count == k - 1 {
                    return true
                }
            }
        }
    }
    return return_value
}

// FUNCTION: AddNeighbors
//
// DESCRIPTION: Determines whether there is an edge between two
// nodes in the generated community graph. If there is, that edge is
// recorded as one of gn's neighbors.

func (gn *GraphNode) AddNeighbors (graph []*GraphNode, k int) {
    for _, node := range graph {
        if gn != node && gn.Kminus1CommonNodes(node, k) {
            gn.AddNeighbor(node)
        }
    }
}

// FUNCTION: CreateCommunityGraph
//
// DESCRIPTION: Transforms every clique created from the original
// graph into a node in the community graph. CreateCommunityGraph
// also determines if there is an edge between vertices and adds the
// appropriate neighbor nodes. For the nodes in the community graph
// to be connected, they must have k-1 vertices in
// common. CreateCommunityGraph returns a valid community graph for
// k.

func CreateCommunityGraph (clique_list *Clique, k int) []*GraphNode {
    var community_graph []*GraphNode
    if clique_list == nil {
        return nil
    }
    for item := clique_list; item != nil; item = item.next {
        label := CreateLabel (item.nodes)
        new_node := NewGraphNode(label, item)
        community_graph = append(community_graph, new_node)
    }

    for _, node := range community_graph {
        node.AddNeighbors(community_graph, k)
    }

    return community_graph
}

func main() {
    var graph []*GraphNode
    k := 3

    // Create the vertices
    for i := 1; i <= 10; i++ {
        label := "v" + strconv.Itoa(i)
        v := NewGraphNode(label, nil)
        graph = append(graph, v)
    }

    // Add all the edges

    // v1
    graph[0].neighbors = append(graph[0].neighbors, graph[1])
    graph[0].neighbors = append(graph[0].neighbors, graph[2])

    // v2
    graph[1].neighbors = append(graph[1].neighbors, graph[0])
    graph[1].neighbors = append(graph[1].neighbors, graph[2])

    // v3
    graph[2].neighbors = append(graph[2].neighbors, graph[1-1])
    graph[2].neighbors = append(graph[2].neighbors, graph[2-1])
    graph[2].neighbors = append(graph[2].neighbors, graph[4-1])
    graph[2].neighbors = append(graph[2].neighbors, graph[5-1])

    // v4
    graph[4-1].neighbors = append(graph[4-1].neighbors, graph[3-1])
    graph[4-1].neighbors = append(graph[4-1].neighbors, graph[5-1])
    graph[4-1].neighbors = append(graph[4-1].neighbors, graph[6-1])
    graph[4-1].neighbors = append(graph[4-1].neighbors, graph[7-1])

    // v5
    graph[5-1].neighbors = append(graph[5-1].neighbors, graph[3-1])
    graph[5-1].neighbors = append(graph[5-1].neighbors, graph[4-1])
    graph[5-1].neighbors = append(graph[5-1].neighbors, graph[6-1])
    graph[5-1].neighbors = append(graph[5-1].neighbors, graph[7-1])

    // v6
    graph[6-1].neighbors = append(graph[6-1].neighbors, graph[4-1])
    graph[6-1].neighbors = append(graph[6-1].neighbors, graph[5-1])
    graph[6-1].neighbors = append(graph[6-1].neighbors, graph[7-1])
    graph[6-1].neighbors = append(graph[6-1].neighbors, graph[8-1])

    // v7
    graph[7-1].neighbors = append(graph[7-1].neighbors, graph[4-1])
    graph[7-1].neighbors = append(graph[7-1].neighbors, graph[5-1])
    graph[7-1].neighbors = append(graph[7-1].neighbors, graph[6-1])
    graph[7-1].neighbors = append(graph[7-1].neighbors, graph[8-1])

    // v8
    graph[8-1].neighbors = append(graph[8-1].neighbors, graph[6-1])
    graph[8-1].neighbors = append(graph[8-1].neighbors, graph[7-1])
    graph[8-1].neighbors = append(graph[8-1].neighbors, graph[9-1])
    graph[8-1].neighbors = append(graph[8-1].neighbors, graph[10-1])

    // v9
    graph[9-1].neighbors = append(graph[9-1].neighbors, graph[8-1])
    graph[9-1].neighbors = append(graph[9-1].neighbors, graph[10-1])

    // v10
    graph[10-1].neighbors = append(graph[10-1].neighbors, graph[8-1])
    graph[10-1].neighbors = append(graph[10-1].neighbors, graph[9-1])

    fmt.Printf("The original graph:\n")
    fmt.Printf("-------------------\n")
    PrintGraph(graph)

    var clique_list *Clique = nil
    for i := 1; i <= 10; i++ {
        candidate_list := GetCliqueCandidates(k, graph[i-1].neighbors)
        if candidate_list != nil {
            temp_clique_list := candidate_list.MakeCliqueList(graph[i-1])
            if clique_list == nil {
                clique_list = temp_clique_list
            } else {
                clique_list = AppendClique(clique_list, temp_clique_list)
            }
        }
    }

    community_graph := CreateCommunityGraph(clique_list, k)
    fmt.Printf("Community graph:\n")
    fmt.Printf("----------------\n")
    PrintGraph(community_graph)
}
<commit_msg>Delete cpm.go<commit_after><|endoftext|>


<commit_before>package ctx

import (
	"context"
	"sync"
	"time"
)

// Doner can block until something is done
type Doner interface {
	Done() <-chan struct{}
}

// DoneChan is a basic implementation of Doner
type DoneChan <-chan struct{}

// Done returns a channel that receives when an action is complete
func (dc DoneChan) Done() <-chan struct{} { return dc }

// Lift takes a chan and wraps it in a Doner
func Lift(c <-chan struct{}) Doner { return DoneChan(c) }

// AsContext creates a context that fires when the Doner fires
func AsContext(d Doner) context.Context {
	c, cancel := context.WithCancel(context.Background())
	Defer(d, cancel)
	return c
}

// WithCancel returns a new Doner that can be cancelled via the associated
// function
func WithCancel(d Doner) (Doner, func()) {
	cq := make(chan struct{})
	return Lift(cq), func() { close(cq) }
}

// Tick returns a <-chan whose range ends when the underlying context cancels
func Tick(d Doner) <-chan struct{} {
	cq := make(chan struct{})
	go func() {
		for {
			select {
			case <-d.Done():
				close(cq)
				return
			case cq <- struct{}{}:
			}
		}
	}()
	return cq
}

// Defer guarantees that a function will be called after a context has cancelled
func Defer(d Doner, cb func()) {
	go func() {
		<-d.Done()
		cb()
	}()
}

// Link returns a channel that fires if ANY of the constituent Doners have fired
func Link(doners ...Doner) DoneChan {
	c := make(chan struct{})
	cancel := func() { close(c) }

	var once sync.Once
	for _, d := range doners {
		Defer(d, func() { once.Do(cancel) })
	}

	return c
}

// Join returns a channel that receives when all constituent Doners have fired
func Join(doners ...Doner) DoneChan {
	var wg sync.WaitGroup
	wg.Add(len(doners))
	for _, d := range doners {
		Defer(d, wg.Done)
	}

	cq := make(chan struct{})
	go func() {
		wg.Wait()
		close(cq)
	}()
	return cq
}

// FTick calls a function in a loop until the Doner has fired
func FTick(d Doner, f func()) {
	for _ = range Tick(d) {
		f()
	}
}

// FTickInterval calls a function repeatedly at a given internval, until the Doner
// has fired.
func FTickInterval(d Doner, t time.Duration, f func()) {
	for _ = range time.NewTicker(t).C {
		select {
		case <-d.Done():
			return
		default:
			f()
		}
	}
}
<commit_msg>Add After func Simplify FTickInterval Return DoneChan from Lift (= robustness principle)<commit_after>package ctx

import (
	"context"
	"sync"
	"time"
)

// Doner can block until something is done
type Doner interface {
	Done() <-chan struct{}
}

// DoneChan is a basic implementation of Doner
type DoneChan <-chan struct{}

// Done returns a channel that receives when an action is complete
func (dc DoneChan) Done() <-chan struct{} { return dc }

// Lift takes a chan and wraps it in a Doner
func Lift(c <-chan struct{}) DoneChan { return DoneChan(c) }

// AsContext creates a context that fires when the Doner fires
func AsContext(d Doner) context.Context {
	c, cancel := context.WithCancel(context.Background())
	Defer(d, cancel)
	return c
}

// After time time has elapsed, the Doner fires
func After(d time.Duration) DoneChan {
	ch := make(chan struct{})
	go func() {
		<-time.After(d)
		close(ch)
	}()
	return ch
}

// WithCancel returns a new Doner that can be cancelled via the associated
// function
func WithCancel(d Doner) (Doner, func()) {
	cq := make(chan struct{})
	return Lift(cq), func() { close(cq) }
}

// Tick returns a <-chan whose range ends when the underlying context cancels
func Tick(d Doner) <-chan struct{} {
	cq := make(chan struct{})
	go func() {
		for {
			select {
			case <-d.Done():
				close(cq)
				return
			case cq <- struct{}{}:
			}
		}
	}()
	return cq
}

// Defer guarantees that a function will be called after a context has cancelled
func Defer(d Doner, cb func()) {
	go func() {
		<-d.Done()
		cb()
	}()
}

// Link returns a channel that fires if ANY of the constituent Doners have fired
func Link(doners ...Doner) DoneChan {
	c := make(chan struct{})
	cancel := func() { close(c) }

	var once sync.Once
	for _, d := range doners {
		Defer(d, func() { once.Do(cancel) })
	}

	return c
}

// Join returns a channel that receives when all constituent Doners have fired
func Join(doners ...Doner) DoneChan {
	var wg sync.WaitGroup
	wg.Add(len(doners))
	for _, d := range doners {
		Defer(d, wg.Done)
	}

	cq := make(chan struct{})
	go func() {
		wg.Wait()
		close(cq)
	}()
	return cq
}

// FTick calls a function in a loop until the Doner has fired
func FTick(d Doner, f func()) {
	for _ = range Tick(d) {
		f()
	}
}

// FTickInterval calls a function repeatedly at a given internval, until the Doner
// has fired.
func FTickInterval(d Doner, t time.Duration, f func()) {
	timer := time.AfterFunc(t, f)
	<-d.Done()
	timer.Stop()
}
<|endoftext|>


<commit_before>// Copyright (c) 2016 IBM Corp. All rights reserved.
// Use of this source code is governed by the Apache License,
// Version 2.0, a copy of which can be found in the LICENSE file.

// Documentation
package main

// This code takes a microservice approach to inserting a room
// into a running Game On! instance. We consume microservices
// provided by Game On! to register a room and we provide our own
// microservice that allows Game On! to bring our room to life.
// In the process of responding to requests from Game On!, we in
// turn will use additonal Game On! microservices to send notifications
// to players and rooms and also to manage certain player aspects,
// such as their next location, during their time in our room.

// The Dance
//
// In this discussion we assume that we are consistent in using
// the same websocket callback every time that our program is
// started.
//
// On starting up, we check to see if our room (by name) has
// already been registered. If not, then we register it using
// an authenticated registration POST.  Once we have determined
// that our room is registered, we use an unauthticated GET to
// gather the names of all rooms that we currently have registered.
// (This code is capable of handling multiple rooms as long as each
// room was registered using the same callback address.)
//
// At this point we start our websocket server to listen for
// service requests from Game On!; the websocket server runs
// forever until our program is terminated.
//
// Future work:
//
// Reconnects to previously-registered rooms are handled
// somewhat naively: if we find a room that we have previously
// registered, then we save info about that room so that
// we can customize later interactions.  However, if those rooms
// were registered to use a different callback address from the
// one that we are currently using, then we will never be asked
// to service those rooms.  A less-simplistic approach would
// save only those rooms that had a callback address matching
// the callback address that we are currently registering;
// a more ambitious approach would be to start another go routine
// to handle each additional callback address that we discover
// in our list of previously-registered rooms.

// Game On!
// Main site: https://game-on.org

// JSON Marshalling Notes
//
// 1. All marshalling is performed using json.MarshalIndent so
//    that any JSON we log is formatted nicely.
//
// 2. The additional tagging that we use to annotate our Go
//    struct types is explained in the Go json documentation, which
//    is currently at https://golang.org/pkg/encoding/json/ . You
//    should ready the documentation for the Marshall function
//    carefully.
//
// 3. Some JSON responses have more information than we
//    need, so we only define marshalling for the fields we
//    care about. See RoomRegistrationResp for an example
//    of a struct designed to keep a subset of the information
//    returned in a response. (We do not need exits or coords
//    so we do not map those fields.)

// Room commands
//
// The handling for each room command (/go, /look, etc.) is kept in
// its own source file and it is typically named room<cmd>.go, as in
// roomchat.go, roomlook.go, etc.

// Deleting rooms
//
// At the time that this code was being written, Game On! did not
// expose a console command to delete a room. Since that initial
// time a console command has been added to delete a room. This
// room's delete code will remain, however, as an example of
// deleting a room from outside of Game On!
<commit_msg>Added information about ack'ing new websocket connections.<commit_after>// Copyright (c) 2016 IBM Corp. All rights reserved.
// Use of this source code is governed by the Apache License,
// Version 2.0, a copy of which can be found in the LICENSE file.

// Documentation
package main

// This code takes a microservice approach to inserting a room
// into a running Game On! instance. We consume microservices
// provided by Game On! to register a room and we provide our own
// microservice that allows Game On! to bring our room to life.
// In the process of responding to requests from Game On!, we in
// turn will use additonal Game On! microservices to send notifications
// to players and rooms and also to manage certain player aspects,
// such as their next location, during their time in our room.

// The Dance
//
// In this discussion we assume that we are consistent in using
// the same websocket callback every time that our program is
// started.
//
// On starting up, we check to see if our room (by name) has
// already been registered. If not, then we register it using
// an authenticated registration POST.  Once we have determined
// that our room is registered, we use an unauthticated GET to
// gather the names of all rooms that we currently have registered.
// (This code is capable of handling multiple rooms as long as each
// room was registered using the same callback address.)
//
// At this point we start our websocket server to listen for
// service requests from Game On!; the websocket server runs
// forever until our program is terminated.
//
// Ack'ing new connections
//
// Game On! opens a new websocket connection each time a player
// enters our room. As soon as the connection is opened and ready
// to use the websocket protocol, we must send an ack message back
// to Game On!. At the time of this writing, the sole purpose of the
// ack message is to send the list of procotol versions that this
// room supports.
//
// Future work:
//
// Reconnects to previously-registered rooms are handled
// somewhat naively: if we find a room that we have previously
// registered, then we save info about that room so that
// we can customize later interactions.  However, if those rooms
// were registered to use a different callback address from the
// one that we are currently using, then we will never be asked
// to service those rooms.  A less-simplistic approach would
// save only those rooms that had a callback address matching
// the callback address that we are currently registering;
// a more ambitious approach would be to start another go routine
// to handle each additional callback address that we discover
// in our list of previously-registered rooms.

// Game On!
// Main site: https://game-on.org

// JSON Marshalling Notes
//
// 1. All marshalling is performed using json.MarshalIndent so
//    that any JSON we log is formatted nicely.
//
// 2. The additional tagging that we use to annotate our Go
//    struct types is explained in the Go json documentation, which
//    is currently at https://golang.org/pkg/encoding/json/ . You
//    should ready the documentation for the Marshall function
//    carefully.
//
// 3. Some JSON responses have more information than we
//    need, so we only define marshalling for the fields we
//    care about. See RoomRegistrationResp for an example
//    of a struct designed to keep a subset of the information
//    returned in a response. (We do not need exits or coords
//    so we do not map those fields.)

// Room commands
//
// The handling for each room command (/go, /look, etc.) is kept in
// its own source file and it is typically named room<cmd>.go, as in
// roomchat.go, roomlook.go, etc.

// Deleting rooms
//
// At the time that this code was being written, Game On! did not
// expose a console command to delete a room. Since that initial
// time a console command has been added to delete a room. This
// room's delete code will remain, however, as an example of
// deleting a room from outside of Game On!
<|endoftext|>


<commit_before>/*

Package levigo provides the ability to create and access LevelDB databases.

levigo.Open() opens and creates databases.

	opts := levigo.NewOptions()
	opts.SetCache(levigo.NewLRUCache(3<<30))
	opts.SetCreateIfMissing(true)
	db, err := levigo.Open("/path/to/db", opts)

DB.Get(), .Put() and .Delete(), respectively, get the data related to a
single key, put data for a single key into the database, and deletes data for
a single key. Don't worry about copying the byte slices in the arguments and
return values of these methods; LevelDB will copy them for you.

	ro := levigo.NewReadOptions()
	wo := levigo.NewWriteOptions()
	// if ro and wo are not used again, be sure to Close them.
	data, err := db.Get(ro, []byte("key"))
	...
	err = db.Put(wo, []byte("anotherkey"), data)
	...
	err = db.Delete(wo, []byte("key"))

For bulk reads, use an Iterator. For ones that you do not want to disturb
your live traffic, be sure to call SetFillCache(false) on the ReadOptions you
use when creating the Iterator.

	ro := levigo.NewReadOptions()
	ro.SetFillCache(false)
	it := db.NewIterator(ro)
	defer it.Close()
	it.Seek(mykey)
	for it = it; it.Valid(); it.Next() {
		munge(it.Key(), it.Value())
	}

Batched, atomic writes can be performed with a WriteBatch and
DB.Write().

	wb := levigo.NewWriteBatch()
	// defer wb.Close or use wb.Clear and reuse.
	wb.Delete([]byte("removed"))
	wb.Put([]byte("added"), []byte("data"))
	wb.Put([]byte("anotheradded"), []byte("more"))
	err := db.Write(wo, wb)
*/
package levigo
<commit_msg>doc.go clean up<commit_after>/*

Package levigo provides the ability to create and access LevelDB databases.

levigo.Open opens and creates databases.

	opts := levigo.NewOptions()
	opts.SetCache(levigo.NewLRUCache(3<<30))
	opts.SetCreateIfMissing(true)
	db, err := levigo.Open("/path/to/db", opts)

DB.Get, DB.Put and DB.Delete, respectively, get the data related to a single
key, put data for a single key into the database, and deletes data for a
single key. You can modify the []byte passed in and returned out of
these methods at any time.

	ro := levigo.NewReadOptions()
	wo := levigo.NewWriteOptions()
	// if ro and wo are not used again, be sure to Close them.
	data, err := db.Get(ro, []byte("key"))
	...
	err = db.Put(wo, []byte("anotherkey"), data)
	...
	err = db.Delete(wo, []byte("key"))

For bulk reads, use an Iterator. For ones that you do not want to disturb
your live traffic, be sure to call SetFillCache(false) on the ReadOptions you
use when creating the Iterator.

	ro := levigo.NewReadOptions()
	ro.SetFillCache(false)
	it := db.NewIterator(ro)
	defer it.Close()
	it.Seek(mykey)
	for it = it; it.Valid(); it.Next() {
		munge(it.Key(), it.Value())
	}

Batched, atomic writes can be performed with a WriteBatch and
DB.Write.

	wb := levigo.NewWriteBatch()
	// defer wb.Close or use wb.Clear and reuse.
	wb.Delete([]byte("removed"))
	wb.Put([]byte("added"), []byte("data"))
	wb.Put([]byte("anotheradded"), []byte("more"))
	err := db.Write(wo, wb)
*/
package levigo
<|endoftext|>


<commit_before>/*
Package telnet provides TELNET and TELNETS client and server implementations
in a style similar to the "net/http" library that is part of the Go standard library,
including support for "middleware"; TELNETS is secure TELNET, with the TELNET protocol
over a secured TLS (or SSL) connection.

Example TELNET Server

ListenAndServe starts a TELNET server with a given address and handler.

	handler := telnet.EchoHandler

	err := telnet.ListenAndServe(":23", handler)
	if nil != err {
		panic(err)
	}

Example TELNETS Server

ListenAndServeTLS starts a (secure) TELNETS server with a given address and handler,
using the specified "cert.pem" and "key.pem" files.

	handler := telnet.EchoHandler

	err := telnet.ListenAndServeTLS(":992", "cert.pem", "key.pem", handler)
	if nil != err {
		panic(err)
	}

TELNET vs TELNETS

If you are communicating over the open Internet, you should be using (the secure) TELNETS and ListenAndServeTLS.

If you are communicating just on localhost, then using just (the un-secure) TELNET and telnet.ListenAndServe may be OK.

If you are not sure which to use, use TELNETS and ListenAndServeTLS.

Example TELNET Shell Server

The previous 2 exaple servers were very very simple. Specifically, they just echoed back whatever
you submitted to it.

If you typed:

	Apple Banana Cherry\r\n

... it would send back:

	Apple Banana Cherry\r\n

(Exactly the same data you sent it.)

A more useful TELNET server can be made using the "github.com/reiver/go-telnet/telsh" sub-package.

The `telsh` sub-package provides "middleware" that enables you to create a "shell" interface (also
called a "command line interface" or "CLI") which most people would expect when using TELNET OR TELNETS.

For example:

	package main

	import (
		"github.com/reiver/go-oi"
		"github.com/reiver/go-telnet"
		"github.com/reiver/go-telnet/telsh"

		"time"
	)

	func main() {

		shellHandler := telsh.NewShellHandler()

		commandName := "date"
		shellHandler.Register(commandName, danceProducer)

		commandName = "animate"
		shellHandler.Register(commandName, animateProducer)

		addr := ":23"
		if err := telnet.ListenAndServe(addr, shellHandler); nil != err {
			panic(err)
		}
	}

Note that in the example, so far, we have registered 2 commands: `date` and `animate`.

For this to actually work, we need to have code for the `date` and `animate` commands.

The actual implemenation for the `date` command could be done like the following:

	func dateHandlerFunc(stdin io.ReadCloser, stdout io.WriteCloser, stderr io.WriteCloser) error {
		const layout = "Mon Jan 2 15:04:05 -0700 MST 2006"
		s := time.Now().Format(layout)

		if _, err := oi.LongWriteString(stdout, s); nil != err {
			return err
		}

		return nil
	}

	func dateProducerFunc(ctx telsh.Context, name string, args ...string) telsh.Handler{
		return telsh.PromoteHandlerFunc(dateHandler)
	}

	var dateProducer = ProducerFunc(dateProducerFunc)

Note that your "real" work is in the `dateHandlerFunc` func.

And the actual implementation for the `animate` command could as done as follows:

	func animateHandlerFunc(stdin io.ReadCloser, stdout io.WriteCloser, stderr io.WriteCloser) error {

		for i:=0; i<20; i++ {
			oi.LongWriteString(stdout, "\r⠋")
			time.Sleep(50*time.Millisecond)

			oi.LongWriteString(stdout, "\r⠙")
			time.Sleep(50*time.Millisecond)

			oi.LongWriteString(stdout, "\r⠹")
			time.Sleep(50*time.Millisecond)

			oi.LongWriteString(stdout, "\r⠸")
			time.Sleep(50*time.Millisecond)

			oi.LongWriteString(stdout, "\r⠼")
			time.Sleep(50*time.Millisecond)

			oi.LongWriteString(stdout, "\r⠴")
			time.Sleep(50*time.Millisecond)

			oi.LongWriteString(stdout, "\r⠦")
			time.Sleep(50*time.Millisecond)

			oi.LongWriteString(stdout, "\r⠧")
			time.Sleep(50*time.Millisecond)

			oi.LongWriteString(stdout, "\r⠇")
			time.Sleep(50*time.Millisecond)

			oi.LongWriteString(stdout, "\r⠏")
			time.Sleep(50*time.Millisecond)
		}
		oi.LongWriteString(stdout, "\r \r\n")

		return nil
	}

	func animateProducerFunc(ctx telsh.Context, name string, args ...string) telsh.Handler{
		return telsh.PromoteHandlerFunc(animateHandler)
	}

	var animateProducer = ProducerFunc(animateProducerFunc)

Again, note that your "real" work is in the `animateHandlerFunc` func.

Generating PEM Files

If you are using the telnet.ListenAndServeTLS func or the telnet.Server.ListenAndServeTLS method, you will need to
supply "cert.pem" and "key.pem" files.

The Go soure code contains a tool for generating these files for you. It can be found at:

	$GOROOT/src/crypto/tls/generate_cert.go

So, for example, if your `$GOROOT` is the "/usr/local/go" directory, then it would be at:

	/usr/local/go/src/crypto/tls/generate_cert.go

If you run the command:

	go run $GOROOT/src/crypto/tls/generate_cert.go --help

... then you get the help information for "generate_cert.go".

Of course, you would replace or set `$GOROOT` with whatever your path actualy is. Again, for example,
if your `$GOROOT` is the "/usr/local/go" directory, then it would be:

	go run /usr/local/go/src/crypto/tls/generate_cert.go --help

To demonstrate the usage of "generate_cert.go", you might run the following to generate certificates
that were bound to the hosts `127.0.0.1` and `localhost`:

	go run /usr/local/go/src/crypto/tls/generate_cert.go --ca --host='127.0.0.1,localhost'

If you are not sure where "generate_cert.go" is on your computer, on Linux and Unix based systems, you might
be able to find the file with the command:

	locate /src/crypto/tls/generate_cert.go

(If it finds it, it should output the full path to this file.)

*/
package telnet
<commit_msg>updated docs<commit_after>/*
Package telnet provides TELNET and TELNETS client and server implementations
in a style similar to the "net/http" library that is part of the Go standard library,
including support for "middleware"; TELNETS is secure TELNET, with the TELNET protocol
over a secured TLS (or SSL) connection.

Example TELNET Server

ListenAndServe starts a TELNET server with a given address and handler.

	handler := telnet.EchoHandler

	err := telnet.ListenAndServe(":23", handler)
	if nil != err {
		panic(err)
	}

Example TELNETS Server

ListenAndServeTLS starts a (secure) TELNETS server with a given address and handler,
using the specified "cert.pem" and "key.pem" files.

	handler := telnet.EchoHandler

	err := telnet.ListenAndServeTLS(":992", "cert.pem", "key.pem", handler)
	if nil != err {
		panic(err)
	}

TELNET vs TELNETS

If you are communicating over the open Internet, you should be using (the secure) TELNETS and ListenAndServeTLS.

If you are communicating just on localhost, then using just (the un-secure) TELNET and telnet.ListenAndServe may be OK.

If you are not sure which to use, use TELNETS and ListenAndServeTLS.

Example TELNET Shell Server

The previous 2 exaple servers were very very simple. Specifically, they just echoed back whatever
you submitted to it.

If you typed:

	Apple Banana Cherry\r\n

... it would send back:

	Apple Banana Cherry\r\n

(Exactly the same data you sent it.)

A more useful TELNET server can be made using the "github.com/reiver/go-telnet/telsh" sub-package.

The `telsh` sub-package provides "middleware" that enables you to create a "shell" interface (also
called a "command line interface" or "CLI") which most people would expect when using TELNET OR TELNETS.

For example:

	package main

	import (
		"github.com/reiver/go-oi"
		"github.com/reiver/go-telnet"
		"github.com/reiver/go-telnet/telsh"

		"time"
	)

	func main() {

		shellHandler := telsh.NewShellHandler()

		commandName := "date"
		shellHandler.Register(commandName, danceProducer)

		commandName = "animate"
		shellHandler.Register(commandName, animateProducer)

		addr := ":23"
		if err := telnet.ListenAndServe(addr, shellHandler); nil != err {
			panic(err)
		}
	}

Note that in the example, so far, we have registered 2 commands: `date` and `animate`.

For this to actually work, we need to have code for the `date` and `animate` commands.

The actual implemenation for the `date` command could be done like the following:

	func dateHandlerFunc(stdin io.ReadCloser, stdout io.WriteCloser, stderr io.WriteCloser) error {
		const layout = "Mon Jan 2 15:04:05 -0700 MST 2006"
		s := time.Now().Format(layout)

		if _, err := oi.LongWriteString(stdout, s); nil != err {
			return err
		}

		return nil
	}

	func dateProducerFunc(ctx telsh.Context, name string, args ...string) telsh.Handler{
		return telsh.PromoteHandlerFunc(dateHandler)
	}

	var dateProducer = ProducerFunc(dateProducerFunc)

Note that your "real" work is in the `dateHandlerFunc` func.

And the actual implementation for the `animate` command could as done as follows:

	func animateHandlerFunc(stdin io.ReadCloser, stdout io.WriteCloser, stderr io.WriteCloser) error {

		for i:=0; i<20; i++ {
			oi.LongWriteString(stdout, "\r⠋")
			time.Sleep(50*time.Millisecond)

			oi.LongWriteString(stdout, "\r⠙")
			time.Sleep(50*time.Millisecond)

			oi.LongWriteString(stdout, "\r⠹")
			time.Sleep(50*time.Millisecond)

			oi.LongWriteString(stdout, "\r⠸")
			time.Sleep(50*time.Millisecond)

			oi.LongWriteString(stdout, "\r⠼")
			time.Sleep(50*time.Millisecond)

			oi.LongWriteString(stdout, "\r⠴")
			time.Sleep(50*time.Millisecond)

			oi.LongWriteString(stdout, "\r⠦")
			time.Sleep(50*time.Millisecond)

			oi.LongWriteString(stdout, "\r⠧")
			time.Sleep(50*time.Millisecond)

			oi.LongWriteString(stdout, "\r⠇")
			time.Sleep(50*time.Millisecond)

			oi.LongWriteString(stdout, "\r⠏")
			time.Sleep(50*time.Millisecond)
		}
		oi.LongWriteString(stdout, "\r \r\n")

		return nil
	}

	func animateProducerFunc(ctx telsh.Context, name string, args ...string) telsh.Handler{
		return telsh.PromoteHandlerFunc(animateHandler)
	}

	var animateProducer = ProducerFunc(animateProducerFunc)

Again, note that your "real" work is in the `animateHandlerFunc` func.

Generating PEM Files

If you are using the telnet.ListenAndServeTLS func or the telnet.Server.ListenAndServeTLS method, you will need to
supply "cert.pem" and "key.pem" files.

If you do not already have these files, the Go soure code contains a tool for generating these files for you.

It can be found at:

	$GOROOT/src/crypto/tls/generate_cert.go

So, for example, if your `$GOROOT` is the "/usr/local/go" directory, then it would be at:

	/usr/local/go/src/crypto/tls/generate_cert.go

If you run the command:

	go run $GOROOT/src/crypto/tls/generate_cert.go --help

... then you get the help information for "generate_cert.go".

Of course, you would replace or set `$GOROOT` with whatever your path actualy is. Again, for example,
if your `$GOROOT` is the "/usr/local/go" directory, then it would be:

	go run /usr/local/go/src/crypto/tls/generate_cert.go --help

To demonstrate the usage of "generate_cert.go", you might run the following to generate certificates
that were bound to the hosts `127.0.0.1` and `localhost`:

	go run /usr/local/go/src/crypto/tls/generate_cert.go --ca --host='127.0.0.1,localhost'

If you are not sure where "generate_cert.go" is on your computer, on Linux and Unix based systems, you might
be able to find the file with the command:

	locate /src/crypto/tls/generate_cert.go

(If it finds it, it should output the full path to this file.)

*/
package telnet
<|endoftext|>


<commit_before>/*
Package color is an ANSI color package to output colorized or SGR defined
output to the standard output. The API can be used in several way, pick one
that suits you.

Use simple and default helper functions with predefined foreground colors:

    color.Cyan("Prints text in cyan.")

    // a newline will be appended automatically
    color.Blue("Prints %s in blue.", "text")

    // More default foreground colors..
    color.Red("We have red")
    color.Yellow("Yellow color too!")
    color.Magenta("And many others ..")

However there are times where custom color mixes are required. Below are some
examples to create custom color objects and use the print functions of each
separate color object.

    // Create a new color object
    c := color.New(color.FgCyan).Add(color.Underline)
    c.Println("Prints cyan text with an underline.")

    // Or just add them to New()
    d := color.New(color.FgCyan, color.Bold)
    d.Printf("This prints bold cyan %s\n", "too!.")

    // Mix up foreground and background colors, create new mixes!
    red := color.New(color.FgRed)

    boldRed := red.Add(color.Bold)
    boldRed.Println("This will print text in bold red.")

    whiteBackground := red.Add(color.BgWhite)
    whiteBackground.Println("Red text with White background.")

You can create PrintXxx functions to simplify even more:

    // Create a custom print function for convenient
    red := color.New(color.FgRed).PrintfFunc()
    red("warning")
    red("error: %s", err)

    // Mix up multiple attributes
    notice := color.New(color.Bold, color.FgGreen).PrintlnFunc()
    notice("don't forget this...")

Or create SprintXxx functions to mix strings with other non-colorized strings:

    yellow := New(FgYellow).SprintFunc()
    red := New(FgRed).SprintFunc()

    fmt.Printf("this is a %s and this is %s.\n", yellow("warning"), red("error"))

    info := New(FgWhite, BgGreen).SprintFunc()
    fmt.Printf("this %s rocks!\n", info("package"))

Windows support is enabled by default. All Print functions works as intended.
However only for color.SprintXXX functions, user should use fmt.FprintXXX and
set the output to color.Output:

	fmt.Fprintf(color.Output, "Windows support: %s", color.GreenString("PASS"))

    info := New(FgWhite, BgGreen).SprintFunc()
    fmt.Fprintf(color.Output, "this %s rocks!\n", info("package"))

Using with existing code is possible. Just use the Set() method to set the
standard output to the given parameters. That way a rewrite of an existing
code is not required.

    // Use handy standard colors.
    color.Set(color.FgYellow)

    fmt.Println("Existing text will be now in Yellow")
    fmt.Printf("This one %s\n", "too")

    color.Unset() // don't forget to unset

    // You can mix up parameters
    color.Set(color.FgMagenta, color.Bold)
    defer color.Unset() // use it in your function

    fmt.Println("All text will be now bold magenta.")
*/
package color
<commit_msg>doc: fix whitspace<commit_after>/*
Package color is an ANSI color package to output colorized or SGR defined
output to the standard output. The API can be used in several way, pick one
that suits you.

Use simple and default helper functions with predefined foreground colors:

    color.Cyan("Prints text in cyan.")

    // a newline will be appended automatically
    color.Blue("Prints %s in blue.", "text")

    // More default foreground colors..
    color.Red("We have red")
    color.Yellow("Yellow color too!")
    color.Magenta("And many others ..")

However there are times where custom color mixes are required. Below are some
examples to create custom color objects and use the print functions of each
separate color object.

    // Create a new color object
    c := color.New(color.FgCyan).Add(color.Underline)
    c.Println("Prints cyan text with an underline.")

    // Or just add them to New()
    d := color.New(color.FgCyan, color.Bold)
    d.Printf("This prints bold cyan %s\n", "too!.")

    // Mix up foreground and background colors, create new mixes!
    red := color.New(color.FgRed)

    boldRed := red.Add(color.Bold)
    boldRed.Println("This will print text in bold red.")

    whiteBackground := red.Add(color.BgWhite)
    whiteBackground.Println("Red text with White background.")

You can create PrintXxx functions to simplify even more:

    // Create a custom print function for convenient
    red := color.New(color.FgRed).PrintfFunc()
    red("warning")
    red("error: %s", err)

    // Mix up multiple attributes
    notice := color.New(color.Bold, color.FgGreen).PrintlnFunc()
    notice("don't forget this...")

Or create SprintXxx functions to mix strings with other non-colorized strings:

    yellow := New(FgYellow).SprintFunc()
    red := New(FgRed).SprintFunc()

    fmt.Printf("this is a %s and this is %s.\n", yellow("warning"), red("error"))

    info := New(FgWhite, BgGreen).SprintFunc()
    fmt.Printf("this %s rocks!\n", info("package"))

Windows support is enabled by default. All Print functions works as intended.
However only for color.SprintXXX functions, user should use fmt.FprintXXX and
set the output to color.Output:

    fmt.Fprintf(color.Output, "Windows support: %s", color.GreenString("PASS"))

    info := New(FgWhite, BgGreen).SprintFunc()
    fmt.Fprintf(color.Output, "this %s rocks!\n", info("package"))

Using with existing code is possible. Just use the Set() method to set the
standard output to the given parameters. That way a rewrite of an existing
code is not required.

    // Use handy standard colors.
    color.Set(color.FgYellow)

    fmt.Println("Existing text will be now in Yellow")
    fmt.Printf("This one %s\n", "too")

    color.Unset() // don't forget to unset

    // You can mix up parameters
    color.Set(color.FgMagenta, color.Bold)
    defer color.Unset() // use it in your function

    fmt.Println("All text will be now bold magenta.")
*/
package color
<|endoftext|>


<commit_before>/*
Package core provides a pure handlers (or middlewares) stack so you can perform actions downstream, then filter and manipulate the response upstream.

The handlers stack

A handler is a function that receives a context.
It can be registered with Use and has the possibility to break the stream or to continue with the next handler in the stack.

Example of a logger, followed by a security headers setter, followed by a response writer:

	// Log
	core.Use(func(c *core.Context) {
		start := time.Now()                                                           // Before the response.
		c.Next()                                                                      // Execute the next handler in the stack (in this case, security headers setter).
		log.Printf(" %s  %s  %s", c.Request.Method, c.Request.URL, time.Since(start)) // After the response.
	})

	// Secure
	core.Use(func(c *core.Context) {
		c.ResponseWriter.Header().Set("X-Frame-Options", "SAMEORIGIN")
		c.ResponseWriter.Header().Set("X-Content-Type-Options", "nosniff")
		c.ResponseWriter.Header().Set("X-XSS-Protection", "1; mode=block")

		c.Next() // Execute the next handler in the stack (in this case, the response writer).
	})

	// Response
	core.Use(func(c *core.Context) {
		fmt.Fprint(c.ResponseWriter, "Hello, World!")
	})

	// Run server
	core.Run()

A clearer visualization of this serving flow:

	request open
	  |- log start
	  |--- secure start
	  |----- response write
	  |--- secure start
	  |- log end
	request close

When using Run, your app is reachable at http://localhost:8080 by default.

If you need more flexibility, you can make a new handlers stack, which is fully compatible with the net/http.Handler interface:

	hs := core.NewHandlersStack()

	hs.Use(func(c *core.Context) {
		fmt.Fprint(c.ResponseWriter, "Hello, World!")
	})

	http.ListenAndServe(":8080", hs)

Flags

These flags are preset:

	-address
		The address to listen and serving on.
		Value is saved in Address.
	-production
		Run the server in production environment.
		Some third-party handlers may have different behaviors depending on the environment.
		Value is saved in Production.

It's up to you to call
	flag.Parse()
in your main function if you want to use them.

Panic recovering

When using Run, your server always recovers from panics, logs the error with stack, and sends a 500 Internal Server Error.
If you want to use a custom handler on panic, give one to HandlePanic.

Handlers and helpers

No handlers or helpers are bundled in the core: it does one thing and does it well.
That's why you need to import all and only the handlers or helpers you need:

	compress
		Clever response compressing
		https://godoc.org/github.com/volatile/compress
	cors
		Cross-Origin Resource Sharing support
		https://godoc.org/github.com/volatile/cors
	i18n
		Simple internationalization
		https://godoc.org/github.com/volatile/i18n
	log
		Requests logging
		https://godoc.org/github.com/volatile/log
	response
		Readable response helper
		https://godoc.org/github.com/volatile/response
	route
		Flexible routing helper
		https://godoc.org/github.com/volatile/route
	secure
		Quick security wins
		https://godoc.org/github.com/volatile/secure
	static
		Simple assets serving
		https://godoc.org/github.com/volatile/static
*/
package core
<commit_msg>Update doc<commit_after>/*
Package core provides a pure handlers (or middlewares) stack so you can perform actions downstream, then filter and manipulate the response upstream.

The handlers stack

A handler is a function that receives a context.
It can be registered with Use and has the possibility to break the stream or to continue with the next handler in the stack.

Example of a logger, followed by a security headers setter, followed by a response writer:

	// Log
	core.Use(func(c *core.Context) {
		start := time.Now()                                                           // Before the response.
		c.Next()                                                                      // Execute the next handler in the stack (in this case, security headers setter).
		log.Printf(" %s  %s  %s", c.Request.Method, c.Request.URL, time.Since(start)) // After the response.
	})

	// Secure
	core.Use(func(c *core.Context) {
		c.ResponseWriter.Header().Set("X-Frame-Options", "SAMEORIGIN")
		c.ResponseWriter.Header().Set("X-Content-Type-Options", "nosniff")
		c.ResponseWriter.Header().Set("X-XSS-Protection", "1; mode=block")

		c.Next() // Execute the next handler in the stack (in this case, the response writer).
	})

	// Response
	core.Use(func(c *core.Context) {
		fmt.Fprint(c.ResponseWriter, "Hello, World!")
	})

	// Run server
	core.Run()

A clearer visualization of this serving flow:

	request open
	  |- log start
	  |--- secure start
	  |----- response write
	  |--- secure start
	  |- log end
	request close

When using Run, your app is reachable at http://localhost:8080 by default.

If you need more flexibility, you can make a new handlers stack, which is fully compatible with the net/http.Handler interface:

	hs := core.NewHandlersStack()

	hs.Use(func(c *core.Context) {
		fmt.Fprint(c.ResponseWriter, "Hello, World!")
	})

	http.ListenAndServe(":8080", hs)

Flags

These flags are preset:

	-address
		The address to listen and serving on.
		Value is saved in Address.
	-production
		Run the server in production environment.
		Some third-party handlers may have different behaviors depending on the environment.
		Value is saved in Production.

It's up to you to call
	flag.Parse()
in your main function if you want to use them.

Panic recovering

When using Run, your server always recovers from panics, logs the error with stack, and sends a 500 Internal Server Error.
If you want to use a custom handler on panic, give one to HandlePanic.

Handlers and helpers

No handlers or helpers are bundled in the core: it does one thing and does it well.
That's why you have to import all and only the handlers or helpers you need:

	compress
		Clever response compressing
		https://godoc.org/github.com/volatile/compress
	cors
		Cross-Origin Resource Sharing support
		https://godoc.org/github.com/volatile/cors
	i18n
		Simple internationalization
		https://godoc.org/github.com/volatile/i18n
	log
		Requests logging
		https://godoc.org/github.com/volatile/log
	response
		Readable response helper
		https://godoc.org/github.com/volatile/response
	route
		Flexible routing helper
		https://godoc.org/github.com/volatile/route
	secure
		Quick security wins
		https://godoc.org/github.com/volatile/secure
	static
		Simple assets serving
		https://godoc.org/github.com/volatile/static
*/
package core
<|endoftext|>


<commit_before>//
// hamming distance calculations in Go
//
// https://github.com/steakknife/hamming
//
// Copyright © 2014, 2015, 2016 Barry Allard
//
// MIT license
//
//
// Usage
//
// The functions are named (CountBits)?(Byte|Uint64)s?.  The plural forms are for slices.  The CountBits.+ forms are Population Count only, where the bare-type forms are Hamming distance.
//
//    import 'github.com/steakknife/hamming'
//
//    // ...
//
//    // hamming distance between values
//    hamming.Byte(0xFF, 0x00) // 8
//    hamming.Byte(0x00, 0x00) // 0
//
//    // just count bits in a byte
//    hamming.CountBitsByte(0xA5), // 4
//
// Got rune? use int32
// Got uint8? use byte
//
package hamming
<commit_msg>slightly better docs<commit_after>//
// hamming distance calculations in Go
//
// https://github.com/steakknife/hamming
//
// Copyright © 2014, 2015, 2016 Barry Allard
//
// MIT license
//
//
// Usage
//
// For functions named CountBits.+s?.  The plural forms are for slices.  The CountBits.+ forms are Population Count only, where the bare-type forms are Hamming distance (number of bits different) between two values.
//
// Optimized assembly PopCnt.+ forms are availble on amd64, and operate just like CountBits.+ (Must check and guard on HasPopCnt() first before trying to call PopCnt.+).
//
//    import 'github.com/steakknife/hamming'
//
//    // ...
//
//    // hamming distance between values
//    hamming.Byte(0xFF, 0x00) // 8
//    hamming.Byte(0x00, 0x00) // 0
//
//    // just count bits in a byte
//    hamming.CountBitsByte(0xA5), // 4
//
// Got rune? use int32
// Got uint8? use byte
//
package hamming
<|endoftext|>


<commit_before>// Package pgx is a PostgreSQL database driver.
/*
pgx provides lower level access to PostgreSQL than the standard database/sql.
It remains as similar to the database/sql interface as possible while
providing better speed and access to PostgreSQL specific features. Import
github.com/jackc/pgx/v4/stdlib to use pgx as a database/sql compatible driver.

Query Interface

pgx implements Query and Scan in the familiar database/sql style.

    var sum int32

    // Send the query to the server. The returned rows MUST be closed
    // before conn can be used again.
    rows, err := conn.Query(context.Background(), "select generate_series(1,$1)", 10)
    if err != nil {
        return err
    }

    // rows.Close is called by rows.Next when all rows are read
    // or an error occurs in Next or Scan. So it may optionally be
    // omitted if nothing in the rows.Next loop can panic. It is
    // safe to close rows multiple times.
    defer rows.Close()

    // Iterate through the result set
    for rows.Next() {
        var n int32
        err = rows.Scan(&n)
        if err != nil {
            return err
        }
        sum += n
    }

    // Any errors encountered by rows.Next or rows.Scan will be returned here
    if rows.Err() != nil {
        return err
    }

    // No errors found - do something with sum

pgx also implements QueryRow in the same style as database/sql.

    var name string
    var weight int64
    err := conn.QueryRow(context.Background(), "select name, weight from widgets where id=$1", 42).Scan(&name, &weight)
    if err != nil {
        return err
    }

Use Exec to execute a query that does not return a result set.

    commandTag, err := conn.Exec(context.Background(), "delete from widgets where id=$1", 42)
    if err != nil {
        return err
    }
    if commandTag.RowsAffected() != 1 {
        return errors.New("No row found to delete")
    }

Connection Pool

See sub-package pgxpool for connection pool.

Base Type Mapping

pgx maps between all common base types directly between Go and PostgreSQL. In
particular:

    Go           PostgreSQL
    -----------------------
    string       varchar
                 text

    // Integers are automatically be converted to any other integer type if
    // it can be done without overflow or underflow.
    int8
    int16        smallint
    int32        int
    int64        bigint
    int
    uint8
    uint16
    uint32
    uint64
    uint

    // Floats are strict and do not automatically convert like integers.
    float32      float4
    float64      float8

    time.Time   date
                timestamp
                timestamptz

    []byte      bytea

Null Mapping

pgx can map nulls in two ways. The first is package pgtype provides types that
have a data field and a status field. They work in a similar fashion to
database/sql. The second is to use a pointer to a pointer.

    var foo pgtype.Varchar
    var bar *string
    err := conn.QueryRow("select foo, bar from widgets where id=$1", 42).Scan(&foo, &bar)
    if err != nil {
        return err
    }

Array Mapping

pgx maps between int16, int32, int64, float32, float64, and string Go slices
and the equivalent PostgreSQL array type. Go slices of native types do not
support nulls, so if a PostgreSQL array that contains a null is read into a
native Go slice an error will occur. The pgtype package includes many more
array types for PostgreSQL types that do not directly map to native Go types.

JSON and JSONB Mapping

pgx includes built-in support to marshal and unmarshal between Go types and
the PostgreSQL JSON and JSONB.

Inet and CIDR Mapping

pgx encodes from net.IPNet to and from inet and cidr PostgreSQL types. In
addition, as a convenience pgx will encode from a net.IP; it will assume a /32
netmask for IPv4 and a /128 for IPv6.

Custom Type Support

pgx includes support for the common data types like integers, floats, strings,
dates, and times that have direct mappings between Go and SQL. In addition,
pgx uses the github.com/jackc/pgx/pgtype library to support more types. See
documention for that library for instructions on how to implement custom
types.

See example_custom_type_test.go for an example of a custom type for the
PostgreSQL point type.

pgx also includes support for custom types implementing the database/sql.Scanner
and database/sql/driver.Valuer interfaces.

If pgx does cannot natively encode a type and that type is a renamed type (e.g.
type MyTime time.Time) pgx will attempt to encode the underlying type. While
this is usually desired behavior it can produce suprising behavior if one the
underlying type and the renamed type each implement database/sql interfaces and
the other implements pgx interfaces. It is recommended that this situation be
avoided by implementing pgx interfaces on the renamed type.

Raw Bytes Mapping

[]byte passed as arguments to Query, QueryRow, and Exec are passed unmodified
to PostgreSQL.

Transactions

Transactions are started by calling Begin. The second argument
can create a transaction with a specified isolation level.

    tx, err := conn.Begin(context.Background(), nil)
    if err != nil {
        return err
    }
    // Rollback is safe to call even if the tx is already closed, so if
    // the tx commits successfully, this is a no-op
    defer tx.Rollback(context.Background())

    _, err = tx.Exec(context.Background(), "insert into foo(id) values (1)")
    if err != nil {
        return err
    }

    err = tx.Commit(context.Background())
    if err != nil {
        return err
    }

Prepared Statements

Prepared statements can be manually created with the Prepare method. However, this is rarely necessary because pgx
includes an automatic statement cache by default. Queries run through the normal Query, QueryRow, and Exec functions are
automatically prepared on first execution and the prepared statement is reused on subsequent executions.

Copy Protocol

Use CopyFrom to efficiently insert multiple rows at a time using the PostgreSQL
copy protocol. CopyFrom accepts a CopyFromSource interface. If the data is already
in a [][]interface{} use CopyFromRows to wrap it in a CopyFromSource interface. Or
implement CopyFromSource to avoid buffering the entire data set in memory.

    rows := [][]interface{}{
        {"John", "Smith", int32(36)},
        {"Jane", "Doe", int32(29)},
    }

    copyCount, err := conn.CopyFrom(
        context.Background(),
        pgx.Identifier{"people"},
        []string{"first_name", "last_name", "age"},
        pgx.CopyFromRows(rows),
    )

CopyFrom can be faster than an insert with as few as 5 rows.

Listen and Notify

Use the underlying pgconn.PgConn for listen and notify.

Logging

pgx defines a simple logger interface. Connections optionally accept a logger
that satisfies this interface. Set LogLevel to control logging verbosity.
Adapters for github.com/inconshreveable/log15, github.com/sirupsen/logrus, and
the testing log are provided in the log directory.
*/
package pgx
<commit_msg>Rewrap doc.go<commit_after>// Package pgx is a PostgreSQL database driver.
/*
pgx provides lower level access to PostgreSQL than the standard database/sql. It remains as similar to the database/sql
interface as possible while providing better speed and access to PostgreSQL specific features. Import
github.com/jackc/pgx/v4/stdlib to use pgx as a database/sql compatible driver.

Query Interface

pgx implements Query and Scan in the familiar database/sql style.

    var sum int32

    // Send the query to the server. The returned rows MUST be closed
    // before conn can be used again.
    rows, err := conn.Query(context.Background(), "select generate_series(1,$1)", 10)
    if err != nil {
        return err
    }

    // rows.Close is called by rows.Next when all rows are read
    // or an error occurs in Next or Scan. So it may optionally be
    // omitted if nothing in the rows.Next loop can panic. It is
    // safe to close rows multiple times.
    defer rows.Close()

    // Iterate through the result set
    for rows.Next() {
        var n int32
        err = rows.Scan(&n)
        if err != nil {
            return err
        }
        sum += n
    }

    // Any errors encountered by rows.Next or rows.Scan will be returned here
    if rows.Err() != nil {
        return err
    }

    // No errors found - do something with sum

pgx also implements QueryRow in the same style as database/sql.

    var name string
    var weight int64
    err := conn.QueryRow(context.Background(), "select name, weight from widgets where id=$1", 42).Scan(&name, &weight)
    if err != nil {
        return err
    }

Use Exec to execute a query that does not return a result set.

    commandTag, err := conn.Exec(context.Background(), "delete from widgets where id=$1", 42)
    if err != nil {
        return err
    }
    if commandTag.RowsAffected() != 1 {
        return errors.New("No row found to delete")
    }

Connection Pool

See sub-package pgxpool for connection pool.

Base Type Mapping

pgx maps between all common base types directly between Go and PostgreSQL. In particular:

    Go           PostgreSQL
    -----------------------
    string       varchar
                 text

    // Integers are automatically be converted to any other integer type if
    // it can be done without overflow or underflow.
    int8
    int16        smallint
    int32        int
    int64        bigint
    int
    uint8
    uint16
    uint32
    uint64
    uint

    // Floats are strict and do not automatically convert like integers.
    float32      float4
    float64      float8

    time.Time   date
                timestamp
                timestamptz

    []byte      bytea

Null Mapping

pgx can map nulls in two ways. The first is package pgtype provides types that have a data field and a status field.
They work in a similar fashion to database/sql. The second is to use a pointer to a pointer.

    var foo pgtype.Varchar
    var bar *string
    err := conn.QueryRow("select foo, bar from widgets where id=$1", 42).Scan(&foo, &bar)
    if err != nil {
        return err
    }

Array Mapping

pgx maps between int16, int32, int64, float32, float64, and string Go slices and the equivalent PostgreSQL array type.
Go slices of native types do not support nulls, so if a PostgreSQL array that contains a null is read into a native Go
slice an error will occur. The pgtype package includes many more array types for PostgreSQL types that do not directly
map to native Go types.

JSON and JSONB Mapping

pgx includes built-in support to marshal and unmarshal between Go types and the PostgreSQL JSON and JSONB.

Inet and CIDR Mapping

pgx encodes from net.IPNet to and from inet and cidr PostgreSQL types. In addition, as a convenience pgx will encode
from a net.IP; it will assume a /32 netmask for IPv4 and a /128 for IPv6.

Custom Type Support

pgx includes support for the common data types like integers, floats, strings, dates, and times that have direct
mappings between Go and SQL. In addition, pgx uses the github.com/jackc/pgx/pgtype library to support more types. See
documention for that library for instructions on how to implement custom types.

See example_custom_type_test.go for an example of a custom type for the PostgreSQL point type.

pgx also includes support for custom types implementing the database/sql.Scanner and database/sql/driver.Valuer
interfaces.

If pgx does cannot natively encode a type and that type is a renamed type (e.g. type MyTime time.Time) pgx will attempt
to encode the underlying type. While this is usually desired behavior it can produce suprising behavior if one the
underlying type and the renamed type each implement database/sql interfaces and the other implements pgx interfaces. It
is recommended that this situation be avoided by implementing pgx interfaces on the renamed type.

Raw Bytes Mapping

[]byte passed as arguments to Query, QueryRow, and Exec are passed unmodified to PostgreSQL.

Transactions

Transactions are started by calling Begin. The second argument can create a transaction with a specified isolation
level.

    tx, err := conn.Begin(context.Background(), nil)
    if err != nil {
        return err
    }
    // Rollback is safe to call even if the tx is already closed, so if
    // the tx commits successfully, this is a no-op
    defer tx.Rollback(context.Background())

    _, err = tx.Exec(context.Background(), "insert into foo(id) values (1)")
    if err != nil {
        return err
    }

    err = tx.Commit(context.Background())
    if err != nil {
        return err
    }

Prepared Statements

Prepared statements can be manually created with the Prepare method. However, this is rarely necessary because pgx
includes an automatic statement cache by default. Queries run through the normal Query, QueryRow, and Exec functions are
automatically prepared on first execution and the prepared statement is reused on subsequent executions.

Copy Protocol

Use CopyFrom to efficiently insert multiple rows at a time using the PostgreSQL copy protocol. CopyFrom accepts a
CopyFromSource interface. If the data is already in a [][]interface{} use CopyFromRows to wrap it in a CopyFromSource
interface. Or implement CopyFromSource to avoid buffering the entire data set in memory.

    rows := [][]interface{}{
        {"John", "Smith", int32(36)},
        {"Jane", "Doe", int32(29)},
    }

    copyCount, err := conn.CopyFrom(
        context.Background(),
        pgx.Identifier{"people"},
        []string{"first_name", "last_name", "age"},
        pgx.CopyFromRows(rows),
    )

CopyFrom can be faster than an insert with as few as 5 rows.

Listen and Notify

Use the underlying pgconn.PgConn for listen and notify.

Logging

pgx defines a simple logger interface. Connections optionally accept a logger that satisfies this interface. Set
LogLevel to control logging verbosity. Adapters for github.com/inconshreveable/log15, github.com/sirupsen/logrus, and
the testing log are provided in the log directory.
*/
package pgx
<|endoftext|>


<commit_before>/*
	Package color extends fmt.Printf with verbs for terminal color highlighting. All it does is replace the verbs with the appropriate terminal escape sequence.

	Highlight verbs:

		%h[attrs]		uses the attrs to highlight the following text
		%r			an abbreviation for %h[reset]

	attrs is a + separated list of Colors (e.g. fgRed) or Attributes (e.g. bold).

	Multiple highlight verbs do not reset preceeding verbs, they add onto them.
	For example, if you set the foreground to green in the first verb, then set the background to red in the second, any text following the second will have a green foreground and a red background.

	Syntax Reference

	16 Foreground Colors:
		%h[fgBlack]
		%h[fgRed]
		%h[fgGreen]
		%h[fgYellow]
		%h[fgBlue]
		%h[fgMagenta]
		%h[fgCyan]
		%h[fgWhite]
		%h[fgDefault]
		%h[fgBrighBlack]
		%h[fgBrightRed]
		%h[fgBrightGreen]
		%h[fgBrightYellow]
		%h[fgBrightBlue]
		%h[fgBrightMagenta]
		%h[fgBrightCyan]
		%h[fgBrightWhite]

	16 Background Colors:
		%h[bgBlack]
		%h[bgRed]
		%h[bgGreen]
		%h[bgYellow]
		%h[bgBlue]
		%h[bgMagenta]
		%h[bgCyan]
		%h[bgWhite]
		%h[bgDefault]
		%h[bgBrighBlack]
		%h[bgBrightRed]
		%h[bgBrightGreen]
		%h[bgBrightYellow]
		%h[bgBrightBlue]
		%h[bgBrightMagenta]
		%h[bgBrightCyan]
		%h[bgBrightWhite]

	256 Colors:
		%h[fgxxx]
		%h[bgxxx]
	Where xxx is any number from 0-255

	Attributes:
		%h[reset] or the %r verb
		%h[bold]
		%h[faint]
		%h[italic]
		%h[underline]
		%h[blink]
		%h[inverse]
		%h[invisible]
		%h[crossedOut]
		%h[doubleUnderline]
		%h[normal]
		%h[notItalic]
		%h[notUnderlined]
		%h[steady]
		%h[positive]
		%h[visible]
		%h[notCrossedOut]

	Mixing:
		%h[fgBlue+bgRed+bold]

	See http://goo.gl/LRLA7o for an explanation of these colors/attributes. Scroll down to the SGR section.
*/
package color
<commit_msg>to le top we go<commit_after>/*
	Package color extends fmt.Printf with verbs for terminal color highlighting. All it does is replace the verbs with the appropriate terminal escape sequence.

	Highlight verbs:

		%h[attrs]		uses the attrs to highlight the following text
		%r			an abbreviation for %h[reset]

	attrs is a + separated list of Colors (e.g. fgRed) or Attributes (e.g. bold).

	Multiple highlight verbs do not reset preceeding verbs, they add onto them.
	For example, if you set the foreground to green in the first verb, then set the background to red in the second, any text following the second will have a green foreground and a red background.

	Syntax Reference

	See http://goo.gl/LRLA7o for an explanation of the colors/attributes. Scroll down to the SGR section.

	16 Foreground Colors:
		%h[fgBlack]
		%h[fgRed]
		%h[fgGreen]
		%h[fgYellow]
		%h[fgBlue]
		%h[fgMagenta]
		%h[fgCyan]
		%h[fgWhite]
		%h[fgDefault]
		%h[fgBrighBlack]
		%h[fgBrightRed]
		%h[fgBrightGreen]
		%h[fgBrightYellow]
		%h[fgBrightBlue]
		%h[fgBrightMagenta]
		%h[fgBrightCyan]
		%h[fgBrightWhite]

	16 Background Colors:
		%h[bgBlack]
		%h[bgRed]
		%h[bgGreen]
		%h[bgYellow]
		%h[bgBlue]
		%h[bgMagenta]
		%h[bgCyan]
		%h[bgWhite]
		%h[bgDefault]
		%h[bgBrighBlack]
		%h[bgBrightRed]
		%h[bgBrightGreen]
		%h[bgBrightYellow]
		%h[bgBrightBlue]
		%h[bgBrightMagenta]
		%h[bgBrightCyan]
		%h[bgBrightWhite]

	256 Colors:
		%h[fgxxx]
		%h[bgxxx]
	Where xxx is any number from 0-255

	Attributes:
		%h[reset] or the %r verb
		%h[bold]
		%h[faint]
		%h[italic]
		%h[underline]
		%h[blink]
		%h[inverse]
		%h[invisible]
		%h[crossedOut]
		%h[doubleUnderline]
		%h[normal]
		%h[notItalic]
		%h[notUnderlined]
		%h[steady]
		%h[positive]
		%h[visible]
		%h[notCrossedOut]

	Mixing:
		%h[fgBlue+bgRed+bold]
*/
package color
<|endoftext|>