From 838c48faffc3f9550552673d489ca141071cc877 Mon Sep 17 00:00:00 2001 From: Luther Monson Date: Sun, 15 Oct 2023 13:44:30 -0700 Subject: [PATCH] updating readme and comments --- README.md | 92 +++++++++++++++++++++++++--------------------------- hosts.go | 8 +++-- hostsline.go | 24 ++++++++++---- 3 files changed, 68 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 57cb9bb..b393dc0 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,62 @@ -# Go library for working with a system's hostsfile -[![codecov](https://codecov.io/gh/goodhosts/hostsfile/branch/master/graph/badge.svg?token=BJQH16QQEH)](https://codecov.io/gh/goodhosts/hostsfile) -## Usage +# Go package for working with a system's hostsfile +[![codecov](https://codecov.io/gh/goodhosts/hostsfile/branch/main/graph/badge.svg?token=BJQH16QQEH)](https://codecov.io/gh/goodhosts/hostsfile) +[![Go Reference](https://pkg.go.dev/badge/github.com/goodhosts/hostsfile.svg)](https://pkg.go.dev/github.com/goodhosts/hostsfile) -Using system default hosts file +Reads the content of a file in the [hosts format](https://en.wikipedia.org/wiki/Hosts_(file)) into go structs for easy manipulation in go programs. When all changes are complete you can `Flush` the hosts file back to disk to save your changes. Supports an indexing system on both ips and hosts for quick management of large hosts files. + +## Simple Usage +Simple usage reading in your system's hosts file and adding an entry for the ip `192.168.1.1` and the host `my-hostname` + +```go +package main + +import ( + "log" + + "github.com/goodhosts/hostsfile" +) + +func main() { + hosts, err := hostsfile.NewHosts() + if err != nil { + log.Fatal(err.Error()) + } + if err := hosts.Add("192.168.1.1", "my-hostname"); err != nil { + log.Fatal(err.Error()) + } + if err := hosts.Flush(); err != nil { + log.Fatal(err.Error()) + } +} ``` -hfile, err := hostsfile.NewHosts() + +### Other Usage +Read in a hosts file from a custom location which is not the system default, this is useful for tests or systems with non-standard hosts file locations. +``` +hosts, err := hostsfile.NewCustomHosts("./my-custom-hostsfile") ``` -Using a custom hostsfile at a specific location +Use `Add` to put an ip and host combination in the hosts file ``` -hfile, err := hostsfile.NewCustomHosts("./my-custom-hostsfile") +err := hosts.Add("192.168.1.1", "my-hostname") ``` -Add an ip entry with it's hosts +`Add` is variadic and can take multiple hosts to add for the same ip ``` -err := hfile.Add("192.168.1.1", "my-hostname", "another-hostname") +err := hosts.Add("192.168.1.1", "my-hostname", "another-hostname") ``` -Remove an ip/host combination +Use `Remove` to drop an ip and host combination from the hosts file ``` -err := hfile.Remove("192.168.1.1", "another-hostname") +err := hosts.Remove("192.168.1.1", "my-hostname") ``` -Flush the hostfile changes back to disk +`Remove` is variadic and can take multiple hosts to remove from the same ip ``` -err := hfile.Flush() +err := hosts.Remove("192.168.1.1", "my-hostname", "another-hostname") ``` -# Full API +Flush the hosts file changes back to disk +``` +err := hosts.Flush() ``` -type Hosts -func NewCustomHosts(osHostsFilePath string) (*Hosts, error) - func NewHosts() (*Hosts, error) - func (h *Hosts) Add(ip string, hosts ...string) error - func (h *Hosts) AddRaw(raw ...string) error - func (h *Hosts) Clean() - func (h *Hosts) Clear() - func (h *Hosts) Flush() error - func (h *Hosts) Has(ip string, host string) bool - func (h *Hosts) HasHostname(host string) bool - func (h *Hosts) HasIp(ip string) bool - func (h *Hosts) HostsPerLine(count int) - func (h *Hosts) IsWritable() bool - func (h *Hosts) Load() error - func (h *Hosts) Remove(ip string, hosts ...string) error - func (h *Hosts) RemoveByHostname(host string) error - func (h *Hosts) RemoveByIp(ip string) error - func (h *Hosts) RemoveDuplicateHosts() - func (h *Hosts) RemoveDuplicateIps() - func (h *Hosts) SortByIp() - func (h *Hosts) SortHosts() -type HostsLine -func NewHostsLine(raw string) HostsLine - func (l *HostsLine) Combine(hostline HostsLine) - func (l *HostsLine) HasComment() bool - func (l *HostsLine) IsComment() bool - func (l *HostsLine) IsMalformed() bool - func (l *HostsLine) IsValid() bool - func (l *HostsLine) RegenRaw() - func (l *HostsLine) RemoveDuplicateHosts() - func (l *HostsLine) SortHosts() - func (l *HostsLine) ToRaw() string -``` \ No newline at end of file diff --git a/hosts.go b/hosts.go index 81727f9..b15593a 100644 --- a/hosts.go +++ b/hosts.go @@ -14,9 +14,11 @@ import ( "github.com/dimchansky/utfbom" ) +// Hosts represents hosts file with the path and parsed contents of each line type Hosts struct { - Path string - Lines []HostsLine + Path string // Path to the location of the hosts file that will be loaded/flushed + Lines []HostsLine // Slice containing all the lines parsed from the hosts file + ips lookup hosts lookup } @@ -361,7 +363,7 @@ func (h *Hosts) combineIP(ip string) { for _, line := range lines { if line.IP == ip { // if you find the ip combine it into newline - newLine.Combine(line) + newLine.combine(line) continue } // add everyone else diff --git a/hostsline.go b/hostsline.go index 247503b..92a6e2b 100644 --- a/hostsline.go +++ b/hostsline.go @@ -7,17 +7,19 @@ import ( "strings" ) +// HostsLine represents a line of the hosts file after being parsed into their respective parts type HostsLine struct { - IP string - Hosts []string - Raw string - Err error - Comment string + IP string // IP found at the beginning of the line + Hosts []string // Hosts split into a slice on the space char + Comment string // Contents of everything after the comment char in the line + + Raw string // Raw contents of the line as parsed in or updated after changes + Err error // Used for error checking during parsing } const commentChar string = "#" -// NewHostsLine return a new instance of HostsLine. +// NewHostsLine takes a raw line as a string and parses it into a new instance of HostsLine e.g. "192.168.1.1 host1 host2 # comments" func NewHostsLine(raw string) HostsLine { output := HostsLine{Raw: raw} @@ -47,6 +49,12 @@ func NewHostsLine(raw string) HostsLine { return output } +// String to make HostsLine a fmt.Stringer +func (l *HostsLine) String() string { + return l.ToRaw() +} + +// ToRaw returns the HostsLine's contents as a raw string func (l *HostsLine) ToRaw() string { var comment string if l.IsComment() { //Whole line is comment @@ -77,7 +85,11 @@ func (l *HostsLine) RemoveDuplicateHosts() { l.RegenRaw() } +// Deprecated: will be made internal, combines the hosts and comments of two lines together, func (l *HostsLine) Combine(hostline HostsLine) { + l.combine(hostline) +} +func (l *HostsLine) combine(hostline HostsLine) { l.Hosts = append(l.Hosts, hostline.Hosts...) if l.Comment == "" { l.Comment = hostline.Comment