emacs

README

goemacs

experimental Emacs modules in Go

Requires dynamic modules support to be built into Emacs (obviously): check that module-file-suffix is not nil.

Example

$ cd examples/hello
$ make test
emacs --batch --load hello.so --eval '(when (featurep (quote hello)) (hello "world"))'
INFO[0000] module initialization started
hello from go init
INFO[0000] creating native function
INFO[0000] creating symbol
INFO[0000] calling function
Hello function!
INFO[0000] calling symbol before it's bound
symbol is not a function
INFO[0000] binding symbol to function
INFO[0000] calling symbol after it's bound
Hello symbol!
INFO[0000] module initialization complete
Hello world!

Credits

The following resources have been immensely useful:

• http://diobla.info/blog-archive/modules-tut.html
• http://nullprogram.com/blog/2016/11/05/
• https://blog.filippo.io/building-python-modules-with-go-1-5/
• http://blog.ralch.com/tutorial/golang-sharing-libraries/
• https://golang.org/cmd/cgo/

Documentation

Index

• func Register(init InitFunction)
• type Callable
• type EmacsCompat
• type Environment
• type Float
• type Function
• type FunctionCallContext
• type FunctionType
• type InitFunction
• type Int
• type List
• type Registry
  • func NewRegistry() Registry
• type StdLib
• type String
• type Symbol
• type UserPointer
• type Value
  • func Error(msg string) (Value, error)
  • func Signal(sym Symbol, val Value) (Value, error)
  • func Throw(sym Symbol, val Value) (Value, error)
• type Vector

Functions

func Register

func Register(init InitFunction)

Register makes sure a function will be called at module initialization

Types

type Callable

type Callable interface {
	Value
	Callable() bool
}

Callable wraps a callable object: function or symbol

type EmacsCompat

type EmacsCompat int

const (
	EMACS25 EmacsCompat = 25
	EMACS26 EmacsCompat = 26
	EMACS27 EmacsCompat = 27
)

type Environment

type Environment interface {
	MakeGlobalRef(Value) Value
	FreeGlobalRef(Value)
	NonLocalExitCheck() error
	GoString(Value) (string, error)
	String(string) String
	GoBool(Value) bool
	Bool(bool) Value
	GoInt(Value) int64
	Int(int64) Int
	GoFloat(Value) float64
	Float(float64) Float
	MakeFunction(FunctionType, int, string, interface{}) Function
	MakeUserPointer(interface{}) UserPointer
	ResolveUserPointer(UserPointer) (interface{}, bool)
	VecSize(Vector) int
	VecSet(Vector, int, Value)
	VecGet(Vector, int) Value

	// additional helpers
	StdLib() StdLib
	RegisterFunction(string, FunctionType, int, string, interface{}) Function
	ProvideFeature(string)

	CheckCompatibility(EmacsCompat) bool
}

Environment provides primitives for emacs modules

type Float

type Float interface {
	Value
}

Float wraps an emacs float number

type Function

type Function interface {
	Callable
}

Function wraps a function object

type FunctionCallContext

type FunctionCallContext interface {
	Environment() Environment
	NumberArgs() int
	Arg(int) Value
	StringArg(int) String
	UserPointerArg(int) UserPointer
	GoStringArg(int) (string, error)
}

FunctionCallContext is the one argument module functions will receive

type FunctionType

type FunctionType func(FunctionCallContext) (Value, error)

FunctionType is the type for module functions

type InitFunction

type InitFunction func(Environment)

InitFunction is the type for functions to be called at module initialization

type Int

type Int interface {
	Value
}

Int wraps an emacs integer

type List

type List interface {
	Value
}

List wraps an emacs list

type Registry

type Registry interface {
	Register(interface{}) int64
	Lookup(int64) (interface{}, bool)
	Unregister(int64)
}

Registry is a key-value store for arbitrary objects

func NewRegistry

func NewRegistry() Registry

NewRegistry creates a new Registry instance

type StdLib

type StdLib interface {
	Funcall(f Callable, args ...Value) (Value, error)
	Eq(a, b Value) bool
	Equal(a, b Value) bool
	Intern(s string) Symbol
	Fset(sym Symbol, f Function)
	Fboundp(sym Symbol) bool
	Provide(sym Symbol)
	Message(s string)
	List(items ...Value) List
	Nil() Value
	T() Value
}

StdLib exposes high-level emacs functions

type String

type String interface {
	Value
	String() string
}

String wraps an emacs string

type Symbol

type Symbol interface {
	Callable
}

Symbol wraps an emacs symbol

type UserPointer

type UserPointer interface {
	Value
}

UserPointer represents a module-created pointer

type Value

type Value interface {
	AsString() String
	AsInt() Int
	AsFloat() Float
	AsSymbol() Symbol
	AsFunction() Function
	AsVector() Vector
	AsList() List
	AsUserPointer() UserPointer
	// contains filtered or unexported methods
}

Value wraps an emacs value

func Error

func Error(msg string) (Value, error)

Error provides shortcut for common error pattern

func Signal

func Signal(sym Symbol, val Value) (Value, error)

Signal performs a signaled non-local exit

func Throw

func Throw(sym Symbol, val Value) (Value, error)

Throw performs a thrown non-local exit

type Vector

type Vector interface {
	Value
	Size() int
	Get(int) Value
	Set(int, Value)
}

Vector wraps an emacs vector