### Build and Install OpenCog Sensory

Source: https://github.com/opencog/sensory/blob/master/README.md

Instructions for building and installing the OpenCog Sensory project. This includes setting up prerequisites like AtomSpace and executing standard CMake and Make commands for compilation and installation.

```bash
mkdir build; cd build; cmake ..
make -j
sudo make install
```

--------------------------------

### Filesystem Navigation Demo (Scheme)

Source: https://github.com/opencog/sensory/blob/master/examples/README.md

Provides a demonstration of navigating a filesystem using the sensori-motor API. This example focuses on file system interaction patterns.

```scheme
; filesys.scm
; Demo of navigating a filesystem
```

--------------------------------

### Interactive Terminal I/O (Scheme)

Source: https://github.com/opencog/sensory/blob/master/examples/README.md

Shows how to stream Atoms/Values to and from an interactive terminal. This example demonstrates real-time input/output interaction.

```scheme
; xterm-io.scm
; Example: Stream Atoms/Values from/to an interactive terminal
```

--------------------------------

### IRC Echo Bot (Scheme)

Source: https://github.com/opencog/sensory/blob/master/examples/README.md

An example of building a simple IRC echo bot. This demo showcases agent construction by attaching API functionalities to processing pipelines.

```scheme
; irc-echo-bot.scm
; IRC echo bot demo
```

--------------------------------

### Link Grammar Definitions and Example

Source: https://github.com/opencog/sensory/blob/master/Architecture.md

This entry consolidates the Link Grammar definitions for xterm and agent, along with the example sentence and its parse diagram. It illustrates how to define device capabilities and system linkages using Link Grammar notation.

```APIDOC
Xterm Capabilities:
   (OPEN- & TXT+) or  (WRITE- & TXT-)

Link Grammar Dictionary:
   agent: (OPEN+ & WRITE+);
   xterm: (OPEN- & TXT+) or (WRITE- & TXT-);

Link Grammar Sentence Example:
   "xterm agent xterm"

Link Grammar Parse Diagram:
      +-------------> TXT ------>+
      +<-- OPEN <--+--> WRITE -->+
      |            |             |
    xterm        agent         xterm
```

--------------------------------

### Using ExecutionOutputLink and GroundedSchema (Scheme)

Source: https://github.com/opencog/sensory/blob/master/examples/README.md

A collection of coding hints, specifically demonstrating the usage of ExecutionOutputLink and GroundedSchema within the system.

```scheme
; hints.scm
; Using ExecutionOutputLink and GroundedSchema
```

--------------------------------

### Open Function Examples

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-H.md

Shows examples of using the `Open` function in OpenCog to establish connections to various stream types, including Terminal, IRC, and Text files, with specific sensory node configurations.

```lisp
(Open (Type 'TerminalStream))
(Open (Type 'IRChatStream)
      (SensoryNode "irc://botty@irc.libera.chat:6667"))
(Open (Type 'TextFileStream)
      (SensoryNode "file:///tmp/demo.txt"))
```

--------------------------------

### Stream File Contents to StreamValue (Scheme)

Source: https://github.com/opencog/sensory/blob/master/examples/README.md

Demonstrates how to stream file contents into a StreamValue object using the sensori-motor API. This is a basic example of input handling.

```scheme
; file-read.scm
; Example: Stream file contents to StreamValue
```

--------------------------------

### IRC API Interaction (Scheme)

Source: https://github.com/opencog/sensory/blob/master/examples/README.md

A demonstration of connecting to IRC and interacting with the network using the API. This covers network communication capabilities.

```scheme
; irc-api.scm
; Demo of connecting to IRC and interacting
```

--------------------------------

### CMake Build Configuration for Sensory Project

Source: https://github.com/opencog/sensory/blob/master/CMakeLists.txt

This snippet details the main CMake build script for the sensory project. It sets the minimum required CMake version, configures installation messages, defines the project name, and finds essential dependencies like CogUtil and AtomSpace. It also includes OpenCog-specific build modules and sets up subdirectories for the project's components and tests.

```CMake
CMAKE_MINIMUM_REQUIRED(VERSION 3.0.1)
SET(CMAKE_INSTALL_MESSAGE LAZY)

PROJECT(sensory)

# ----------------------------------------------------------
# Cogutil. Required prerequisite.
FIND_PACKAGE(CogUtil 2.0.3 CONFIG REQUIRED)
IF(COGUTIL_FOUND)
	SET(HAVE_COGUTIL 1)

	# Add the 'cmake' directory from cogutil to search path
	list(APPEND CMAKE_MODULE_PATH  ${COGUTIL_DATA_DIR}/cmake)

	# Needed to set OC_CMAKE_DIR
	if (NOT DEFINED ATOMSPACE_DATA_DIR)
		set (ATOMSPACE_DATA_DIR "${COGUTIL_DATA_DIR}")
	endif (NOT DEFINED ATOMSPACE_DATA_DIR)

	include(OpenCogGccOptions)
	include(OpenCogLibOptions)
	include(OpenCogInstallOptions)
	include(Summary)

ENDIF()

# AtomSpace
FIND_PACKAGE(AtomSpace 5.0.4 CONFIG REQUIRED)
IF(ATOMSPACE_FOUND)
	SET(HAVE_ATOMSPACE 1)
ENDIF()

# ----------------------------------------------------------
# Guile Python and Cython

include(OpenCogFindGuile)
include(OpenCogFindPython)

# Load cmake functions defined in cogutil repo that depend on Guile.
INCLUDE(OpenCogMacros)
INCLUDE(OpenCogGuile)
INCLUDE(OpenCogCython)

# ----------------------------------------------------------
ADD_SUBDIRECTORY (opencog)
ADD_SUBDIRECTORY (cmake)

# Unit tests
ADD_SUBDIRECTORY (tests EXCLUDE_FROM_ALL)

# ===================================================================
# Show a summary of what we found, what we will do.

SUMMARY_ADD("Python bindings" "Python (cython) bindings" HAVE_CYTHON)
SUMMARY_SHOW()
```

--------------------------------

### Copy Text Between Two Xterms (Scheme)

Source: https://github.com/opencog/sensory/blob/master/examples/README.md

Demonstrates copying text between two separate interactive terminal sessions. This example highlights inter-process communication via terminals.

```scheme
; xterm-bridge.scm
; Copying text between two xterms
```

--------------------------------

### Stream Atoms/Values to File (Scheme)

Source: https://github.com/opencog/sensory/blob/master/examples/README.md

Illustrates the process of streaming Atoms or Values to a file using the sensori-motor API. This covers basic output operations.

```scheme
; file-write.scm
; Example: Stream Atoms/Values to a file
```

--------------------------------

### Open Terminal and String Compare

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-G.md

Opens a terminal stream and sets up an evaluation to compare input against a specific string literal. This example illustrates the initial setup for reading terminal input.

```Scheme
(define term-loc (ValueOf (Anchor "crawler") (Predicate "term")))
(cog-execute!
	(SetValue (Anchor "crawler") (Predicate "term")
	(Open (Type 'TerminalStream))))

(cog-evaluate!
	(Equal input-loc (LinkSignature (Type 'LinkValue) (Item "xxx\n"))))
```

--------------------------------

### Install Sensory Terminal Target

Source: https://github.com/opencog/sensory/blob/master/opencog/atoms/terminal/CMakeLists.txt

Installs the built `sensory-terminal` shared library and its associated export targets into the appropriate system directories. This makes the library available for use by other projects.

```cmake
INSTALL (TARGETS sensory-terminal EXPORT AtomSpaceTargets
	DESTINATION "lib${LIB_DIR_SUFFIX}/opencog"
)
```

--------------------------------

### Guile Sensory Extension and Module Setup

Source: https://github.com/opencog/sensory/blob/master/opencog/sensory/CMakeLists.txt

Adds a Guile extension for sensory functionality and registers a Guile module with its dependencies. This allows the sensory components to be used within the Guile interpreter, specifying the module files and destination.

```Guile
add_guile_extension(SCM_CONFIG sensory "opencog-ext-path-sensory")
add_guile_module(FILES
   sensory.scm
   ${CMAKE_CURRENT_BINARY_DIR}/types/sensory_types.scm
   MODULE_DESTINATION "${GUILE_SITE_DIR}/opencog/sensory"
   DEPENDS sensory_atom_types
)
```

--------------------------------

### Sensory Module CMake Configuration

Source: https://github.com/opencog/sensory/blob/master/opencog/atoms/sensory/CMakeLists.txt

This CMakeLists.txt file configures the build process for the OpenCog sensory module. It defines a shared library named 'sensory', lists its source files, specifies include directories, sets up library dependencies, and defines installation rules for the built library and header files.

```cmake
# The atom_types.h file is written to the build directory
INCLUDE_DIRECTORIES(${CMAKE_BINARY_DIR})
INCLUDE_DIRECTORIES(${CMAKE_SOURCE_DIR})

ADD_LIBRARY (sensory SHARED
	LookatLink.cc
	OpenLink.cc
	OutputStream.cc
	SensoryNode.cc
	StreamEqualLink.cc
	WriteLink.cc
)

# Without this, parallel make will race and crap up the generated files.
ADD_DEPENDENCIES(sensory sensory_atom_types)

TARGET_LINK_LIBRARIES(sensory
	sensory-types
	${ATOMSPACE_LIBRARIES}
	${COGUTIL_LIBRARY}
)

INSTALL (TARGETS sensory EXPORT SensoryTargets
	DESTINATION "lib${LIB_DIR_SUFFIX}/opencog"
)

INSTALL (FILES
	LookatLink.h
	OpenLink.h
	OutputStream.h
	SensoryNode.h
	StreamEqualLink.h
	WriteLink.h
	DESTINATION "include/opencog/atoms/sensory"
)
```

--------------------------------

### OpenCog Section Structure Example

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-E.md

Illustrates the structure of an OpenCog 'Section' with 'Anchor' and 'ConnectorSeq' components. This pattern is used for organizing and potentially searching data within the system.

```scheme
(Section
    (Anchor "some object")
    (Predicate "method name")
    (ConnectorSeq ...))
```

--------------------------------

### MyFooAgent Linkage Example

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-C.md

Demonstrates the process of looking up and describing the linkage capabilities of a 'MyFooAgent' type using cog-execute.

```Scheme
(cog-execute! (Lookup (Type 'MyFooAgent)))
```

--------------------------------

### CMake Build Configuration for Sensory Module

Source: https://github.com/opencog/sensory/blob/master/opencog/atoms/filedir/CMakeLists.txt

This snippet details the CMake commands used to configure the build for the OpenCog sensory module. It includes setting include directories, defining a shared library, specifying build dependencies, linking necessary libraries, and defining installation rules for targets and headers.

```cmake
INCLUDE_DIRECTORIES(${CMAKE_BINARY_DIR})
INCLUDE_DIRECTORIES(${CMAKE_SOURCE_DIR})

ADD_LIBRARY (sensory-filedir SHARED
	FileSysStream.cc
	TextFileStream.cc
)

ADD_DEPENDENCIES(sensory-filedir sensory_atom_types)

TARGET_LINK_LIBRARIES(sensory-filedir
	sensory
	sensory-types
	${ATOMSPACE_LIBRARIES}
	${COGUTIL_LIBRARY}
)

INSTALL (TARGETS sensory-filedir EXPORT AtomSpaceTargets
	DESTINATION "lib${LIB_DIR_SUFFIX}/opencog"
)

INSTALL (FILES
	FileSysStream.h
	TextFileStream.h
	DESTINATION "include/opencog/atoms/sensory"
)
```

--------------------------------

### OpenCog Execution Examples

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-H.md

Demonstrates the use of `cog-execute!` with `Lookat` to access different stream types in OpenCog. It highlights the requirement for underlying C++ implementations with `OutputStream::describe()`.

```lisp
(cog-execute! (Lookat (Type 'FileSysStream)))
(cog-execute! (Lookat (Type 'FooBarStream)))
```

--------------------------------

### Install Sensory Terminal Header

Source: https://github.com/opencog/sensory/blob/master/opencog/atoms/terminal/CMakeLists.txt

Installs the `TerminalStream.h` header file into the include directory structure. This allows other C++ projects to include the necessary headers for the sensory-terminal library.

```cmake
INSTALL (FILES
	TerminalStream.h
	DESTINATION "include/opencog/atoms/sensory"
)
```

--------------------------------

### TerminalStream Linkage Example

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-C.md

Demonstrates the process of looking up and describing the linkage capabilities of a 'TerminalStream' type using cog-execute.

```Scheme
(cog-execute! (Lookup (Type 'TerminalStream)))
```

--------------------------------

### CMake Build Configuration for OpenCog Sensory Module

Source: https://github.com/opencog/sensory/blob/master/opencog/cython/CMakeLists.txt

Configures the build process for the OpenCog sensory module using CMake. Sets C++ compiler flags, defines Cython compilation flags, specifies module dependencies, links necessary libraries, and defines installation targets.

```CMake
#
# Need to use -fno-strict-aliasing when compiling cython code, in order
# to avoid nasty compiler warnings about aliasing.  Cython explicitly
# performs aliasing, in order to emulate python object inheritance.
# See, for example,
# https://groups.google.com/forum/#!topic/cython-users/JV1-KvIUeIg
#
SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fno-strict-aliasing")
INCLUDE_DIRECTORIES(
	${Python3_INCLUDE_DIRS}
	${CMAKE_CURRENT_SOURCE_DIR}
	${CMAKE_CURRENT_BINARY_DIR}
)

# The -3 flag means "build for python3"
SET(CYTHON_FLAGS "-3" "-f" "-Wextra")

# The python module name is taken from the pyx filename. Thus, the file
# sensory.pyx means that module name will be 'opencog.sensory'. This will
# have an autogenerated PyInit_sensory() in it, again, based on the module
# name.
CYTHON_ADD_MODULE_PYX(sensory
	"sensory.pxd"
	"../sensory/types/sensory_types.pyx"
	"../sensory/types/atom_types.h")

ADD_LIBRARY(sensory_cython SHARED
	sensory.cpp
)

ADD_DEPENDENCIES(sensory_cython sensory_atom_types)

# The NO_AS_NEEDED forces the shared library ctors to run
# for the libsensory-whatever.so. These are needed to get
# the assorted atom type factories to get installed into
# the atompace nameserver.
TARGET_LINK_LIBRARIES(sensory_cython
	${NO_AS_NEEDED}
	sensory-types
	sensory-irc
	sensory-filedir
	sensory-terminal
	sensory
	atomspace
	${Python3_LIBRARIES}
)

SET_TARGET_PROPERTIES(sensory_cython PROPERTIES
	PREFIX ""
	OUTPUT_NAME sensory)

### install the modules ###
INSTALL(TARGETS
	sensory_cython
	DESTINATION "${PYTHON_DEST}")

```

--------------------------------

### CMake Build for OpenCog Sensory IRC Library

Source: https://github.com/opencog/sensory/blob/master/opencog/atoms/irc/CMakeLists.txt

Configures the build process for the sensory-irc shared library using CMake. It defines library targets, links necessary dependencies, and specifies installation paths for the OpenCog project.

```CMake
INCLUDE_DIRECTORIES(${CMAKE_BINARY_DIR})
INCLUDE_DIRECTORIES(${CMAKE_SOURCE_DIR})

ADD_LIBRARY (sensory-irc SHARED
	IRC.cc
	IRChatStream.cc
)

# Without this, parallel make will race and crap up the generated files.
ADD_DEPENDENCIES(sensory-irc sensory_atom_types)

TARGET_LINK_LIBRARIES(sensory-irc
	sensory
	sensory-types
	${ATOMSPACE_LIBRARIES}
	${COGUTIL_LIBRARY}
)

INSTALL (TARGETS sensory-irc EXPORT AtomSpaceTargets
	DESTINATION "lib${LIB_DIR_SUFFIX}/opencog"
)

INSTALL (FILES
	IRChatStream.h
	DESTINATION "include/opencog/atoms/sensory"
)
```

--------------------------------

### Conditional Rewrite Pattern Example

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-F.md

Demonstrates how to use CondLink within a rewrite pattern to make decisions based on input variables. It assumes variables like '$file-type' and '$file-name' are provided by an input pattern.

```Atomese
(Cond
   (Equal (Variable "$file-type") (Node "dir"))
   (Open (Variable "$file-name")))
```

--------------------------------

### Sensory Module Build Configuration

Source: https://github.com/opencog/sensory/blob/master/opencog/sensory/types/CMakeLists.txt

This CMake script sets up the build environment for the OpenCog sensory module. It defines custom targets for generating atom types in C++, Scheme, and Python, adds a shared library for the module, links necessary libraries, and specifies installation paths for targets and headers.

```cmake
OPENCOG_GEN_CXX_ATOMTYPES(sensory_types.script
	atom_types.h
	atom_types.definitions
	atom_types.inheritance)

OPENCOG_GEN_SCM_ATOMTYPES(sensory_types.script sensory_types.scm)
OPENCOG_GEN_PYTHON_ATOMTYPES(sensory_types.script sensory_types.pyx)

ADD_CUSTOM_TARGET(sensory_atom_types
	DEPENDS atom_types.h sensory_types.scm sensory_types.pyx)

# The atom_types.h file is written to the build directory
INCLUDE_DIRECTORIES(${CMAKE_BINARY_DIR})

ADD_LIBRARY(sensory-types SHARED
	sensory_types_init.cc
)

# Without this, parallel make will race and crap up the generated files.
ADD_DEPENDENCIES(sensory-types sensory_atom_types)

TARGET_LINK_LIBRARIES(sensory-types
	${ATOMSPACE_atomtypes_LIBRARY}
)

INSTALL (TARGETS sensory-types
	EXPORT SensoryTargets
	LIBRARY DESTINATION "lib${LIB_DIR_SUFFIX}/opencog"
)

INSTALL (FILES
	${CMAKE_CURRENT_BINARY_DIR}/atom_types.h
	DESTINATION "include/opencog/sensory/types"
)

add_guile_extension(SCM_CONFIG sensory-types "opencog-ext-path-sensory-types")
```

--------------------------------

### CMake: Configure Sensory Package

Source: https://github.com/opencog/sensory/blob/master/cmake/CMakeLists.txt

This CMake script sets up the necessary configuration files for the Sensory library, enabling it to be found and used by other CMake projects via `find_package`. It defines targets, versions, and installation paths, ensuring proper integration into a build system.

```cmake
SET(SEMANTIC_VERSION 0.3.1)

export(EXPORT SensoryTargets
	FILE "${CMAKE_CURRENT_BINARY_DIR}/Sensory/SensoryTargets.cmake"
)

set(ConfigPackageLocation lib/cmake/Sensory)

install(EXPORT SensoryTargets
	FILE SensoryTargets.cmake
	DESTINATION ${ConfigPackageLocation}
)

include(CMakePackageConfigHelpers)

configure_package_config_file(SensoryConfig.cmake.in
	${CMAKE_CURRENT_BINARY_DIR}/SensoryConfig.cmake
	INSTALL_DESTINATION lib/Sensory/cmake
	PATH_VARS CMAKE_INSTALL_PREFIX
)

write_basic_package_version_file(
	"${CMAKE_CURRENT_BINARY_DIR}/SensoryConfigVersion.cmake"
	VERSION ${SEMANTIC_VERSION}
	COMPATIBILITY SameMajorVersion
)

INSTALL(FILES
	${CMAKE_CURRENT_BINARY_DIR}/SensoryConfigVersion.cmake
	${CMAKE_CURRENT_BINARY_DIR}/SensoryConfig.cmake
	DESTINATION ${ConfigPackageLocation}
)
```

--------------------------------

### HTML DTD Example

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-B.md

An oversimplified example of a Document Type Definition (DTD) for HTML, illustrating the concept of defining data types and element structures.

```HTML
<!ELEMENT html (head, body)>
<!ELEMENT p (#PCDATA | p | ul | dl | table | h1|h2|h3)*>
```

--------------------------------

### OpenCog IRC Stream Initialization and Interaction

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-B.md

Demonstrates how to initialize an IRC stream using `cog-execute!` with `Open`, `TypeNode`, and `SensoryNode`. It also shows how to interact with the stream to list available commands like 'help', 'list', and 'join'.

```lisp
(define irc-stream (cog-execute!\n	(Open\n		(TypeNode 'IRChatStream)\n		(SensoryNode "irc://nick@server/"))))\n\nirc-stream ; list available commands, e.g. list channels, join\n; Return will be\n(LinkValue\n	(ActionNode "help")   ; help menu\n	(ActionNode "list")   ; listing of channels\n	(ActionNode "join"))  ; channel to join
```

--------------------------------

### Parsing and Hooking Up Node.js Systems

Source: https://github.com/opencog/sensory/blob/master/Architecture.md

The 'npm run make' command is used to parse the Node.js system and perform necessary hookups based on the device descriptions provided in package files. This process integrates different agents and connectors into a functioning network.

```bash
npm run make
```

--------------------------------

### Atomese Wiring Paradigm

Source: https://github.com/opencog/sensory/blob/master/README.md

The OpenCog project's approach to 'wiring' using Atomese, aiming to generalize the concept of connecting components and data flow across diverse domains.

```APIDOC
Atomese_Wiring:
  Concept: Generalization of 'wiring' and 'hooking things together'.
  Domain: Sensory-motor systems, self-description using Link Grammar.
  Comparison: Aims to be a superset of EDA languages (VHDL, Verilog) and Compiler IRs (RTL, GIMPLE).
  Key_Features:
    - Uses Atomese for wiring, not Verilog.
    - Captures generic abstraction of wiring.
    - Values are transient, Atoms in AtomSpace are static repositories.
    - Rewrite rule: Moves Values into Atoms (storage) and streams Atoms out into Values.
  Analogy:
    - CPU registers (computation) vs. System RAM (storage).
    - Electrical circuits (current on wires) vs. Plumbing (substances in pipes).
```

--------------------------------

### Build Configuration Directives

Source: https://github.com/opencog/sensory/blob/master/opencog/CMakeLists.txt

Core build system commands for setting up the OpenCog sensory project. These directives manage project structure, conditional compilation, and configuration file deployment.

```Guile Scheme
DECLARE_GUILE_CONFIG_TARGET(SCM_CONFIG "opencog sensory-config" "SENSORY_TEST")

ADD_SUBDIRECTORY (atoms)
ADD_SUBDIRECTORY (sensory)

# Python bindings
IF (HAVE_CYTHON)
   ADD_SUBDIRECTORY (cython)
ENDIF (HAVE_CYTHON)

# Testing framework boilerplate.

WRITE_GUILE_CONFIG(${GUILE_BIN_DIR}/opencog/sensory-config.scm SCM_CONFIG TRUE)
WRITE_GUILE_CONFIG(${GUILE_BIN_DIR}/opencog/sensory-config-installable.scm SCM_CONFIG FALSE)
INSTALL(FILES ${GUILE_BIN_DIR}/opencog/sensory-config-installable.scm
DESTINATION ${GUILE_SITE_DIR}/opencog RENAME sensory-config.scm)
```

--------------------------------

### Enable Unit Testing

Source: https://github.com/opencog/sensory/blob/master/tests/CMakeLists.txt

Enables the unit testing framework for the project. This function is typically called at the beginning of a test suite setup.

```C++
ENABLE_TESTING()
```

--------------------------------

### OpenCog IRC Channel Join Action

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-B.md

Illustrates joining a specific IRC channel ('#opencog') by opening a stream with context and specifying the 'join' action. This method uses `Open` to establish the connection and context for the action.

```lisp
(define look-stream (cog-execute!\n	(Open\n		irc-stream  ; this provides context\n		(ActionNode "join")\n		(ItemNode "#opencog"))))
```

--------------------------------

### File Node and I/O Operations

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-A.md

Describes how TextFileNode might be used to open files for reading or writing, with URL-based modes. It also shows how to execute operations on these nodes.

```APIDOC
File Node Execution:
  (cog-io-open (TextFileNode "file:///tmp/foo"))

  (cog-execute! (TextFileNode "file:///file/system/path"))

File URL Scheme:
  file:/path
  file:///path
  file://./path   ; dot is localhost
  file://host/path

File Mode Specification:
  file:mode//path
  where mode is read, write, append, truncate, etc.
```

--------------------------------

### Lisp-like Execution and Node Structures

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-A.md

Illustrates early ideas for representing execution and data structures using a Lisp-like syntax, including concepts like nodes, links, and value retrieval.

```lisp
(ExecutionOutput
	(FileNode "///")  ; DefinedSchema  GroundedPredicate PROCEDURE_NODE
	(ValueOf stuff))

; nodes store state info with node
; links can too, because outoging. Sort of ish.
; links have args know how to execute.
; Just be a FunctionLink instead of ExecutionOutput
; Or ExecutableLink EXECUTABLE_LINK
```

```lisp
(FileWriteLink
	(Node "file:///place")  ; Any Node at all can hold a string.
	(ValueOf stuff))  ; stuff to write fetched from this.

(WriteLink
	(Node "url:///place") ; Dispatch, branch on url
	(ValueOf stuff))

(WriteLink
	(FileNode "file:///place")  ; FileNode knows how to do it.
	(ValueOf stuff))
```

```lisp
(FileReadLink               ; Used to place read data somewhere.
	(Node "file:///place")
	(SetValue stuff))

(ReadLink
	(FileNode "file:///place"))

(ReadLink
	(IRCBotNode "irc:///place?config=stuff&more=stuff"))
```

--------------------------------

### Execute File Stream Lookup

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-B.md

Demonstrates initiating interaction with a file stream by performing a lookup operation.

```lisp-like
(cog-execute! (Lookup (Type 'FileStream)))
```

--------------------------------

### OpenCog Sensory Project Capabilities

Source: https://github.com/opencog/sensory/blob/master/README.md

Lists the basic interactive and I/O stream functionalities provided by the OpenCog sensory project. These are foundational elements for agent interaction with the environment.

```APIDOC
Provides:
* Basic interactive terminal I/O stream.
* Basic File I/O stream.
* Prototype Filesystem navigation stream.
* Prototype IRC chatbot stream.
```

--------------------------------

### Execute Lookup Action

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-B.md

Demonstrates executing a lookup action to find an IRC chat stream. This is an initial step to interact with a sensory stream.

```lisp-like
(cog-execute! (Lookup (Type 'IRChatStream)))
```

--------------------------------

### Node.js Package Files as Device Descriptions

Source: https://github.com/opencog/sensory/blob/master/Architecture.md

Node.js package.json and package-lock.json files serve as sensory or agent description files. They define the inputs and outputs of a particular Node.js device or agent, enabling the system to understand its capabilities and connections.

```text
package.json
package-lock.json
```

--------------------------------

### Generic Stream Constructor

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-A.md

Proposes a generic constructor for creating stream instances, such as TextFileStream, by specifying the stream type and a sensory node containing the source information.

```APIDOC
OpenLink Constructor:
  (OpenLink
    (TypeNode 'TextFileStream)
    (SensoryNode "file:///file/system/path"))

This would return an instance of the specified stream type, using the ValueFactory to create it and passing the SensoryNode as an argument.
```

--------------------------------

### MyFooAgent API Documentation

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-C.md

Details the structure and connectors for MyFooAgent, specifically its 'piping agent' capabilities for issuing multiple OpenLink and WriteLink connectors.

```APIDOC
MyFooAgent:
  Item: "piping agent"
  ConnectorSeq (OpenLink Issuers):
    - Connector (Sex "issuer") (Type "OpenLink")
    - Connector (Sex "issuer") (Type "OpenLink")
  ConnectorSeq (WriteLink Issuers):
    - Connector (Sex "issuer") (Type "WriteLink")
    - Connector (Sex "issuer") (Type "WriteLink")
```

--------------------------------

### IRC Channel Join Command Description

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-B.md

Defines the structure for the IRC 'JOIN' command, including connectors for sending the command, the JOIN string, and the channel name, as well as the expected reply format.

```lisp-like
(Section
		(Item "This is what channel JOIN messages are like")
		(ConnectorSeq
			(Connector
				(Sex "command")
				(Type 'WriteLink))
			(Connector
				(Sex "command")
				(Item "JOIN"))
			(Connector
				(Sex "command")
            (Type 'StringValue))
			(Connector
				(Sex "reply")
				(LinkSignature
					(Type 'LinkValue)
					(Type 'StringValue))))
```

--------------------------------

### Directory Listing with StringValues

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-F.md

Illustrates an initial representation of directory paths obtained from a file system listing command like 'ls'. The paths are encapsulated within StringValue nodes, grouped under a LinkValue.

```Atomese
(LinkValue
  (StringValue "file:///etc/vim")
  (StringValue "file:///etc/opt")
  (StringValue "file:///etc/nvme")
  (StringValue "file:///etc/ldap")
  (StringValue "file:///etc/lvm"))
```

--------------------------------

### Atomese KVP Object Method Interpretation

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-E.md

This snippet illustrates how a Key-Value Pair (KVP) system can interpret an atom combined with a key as a representation of an object and its method. It provides a conceptual syntax for invoking methods on objects within the Atomese framework.

```Atomese
(ValueOf (Anchor "some object") (Predicate "method name"))
```

--------------------------------

### File Stream ChoiceLink Structure

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-B.md

Illustrates the menu of actions available for a file stream, similar to other streams, offering options like 'Open' and 'Write'.

```lisp-like
(ChoiceLink
		(Section (Item "Open") ...)
		(Section (Item "Write") ...)
   ...)
```

--------------------------------

### Execute Open IRC Stream Action

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-B.md

Shows the concrete action of opening an IRC chat stream by providing the specific IRC URL.

```lisp-like
(cog-execute!
   (Open
      (Type 'IRChatStream)
      (SensoryNode "irc://botty@irc.libera.chat:6667")))
```

--------------------------------

### Configure Include Directories

Source: https://github.com/opencog/sensory/blob/master/opencog/atoms/terminal/CMakeLists.txt

Sets the include paths for the build process, pointing to the binary and source directories. This ensures that header files can be found during compilation.

```cmake
INCLUDE_DIRECTORIES(${CMAKE_BINARY_DIR})
INCLUDE_DIRECTORIES(${CMAKE_SOURCE_DIR})
```

--------------------------------

### WriteLink API Proposal

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-A.md

Proposes a new signature for the WriteLink API to support iterators for output. It details how the link should accept a stream for writing and the data to be written, emphasizing the need for executable values to represent streams.

```APIDOC
WriteLink API (Initial Idea):
  (WriteLink
    (TextFileNode "file:///tmp/foo")
    (Value stream of things to write)
    (Iterator to write to))

WriteLink API (Final Idea):
  (WriteLink
    (TextStream)   ; iterator to write to.
    (StringValue)) ; strings to write

Note: Links cannot store Values directly, so these must be executable things that return the desired streams.
```

--------------------------------

### Atomese Agent Framework Design Goals

Source: https://github.com/opencog/sensory/blob/master/README.md

Outlines the design goals for the Atomese agent framework, focusing on environmental interaction capabilities such as reading/writing files, navigating directories, and functioning as chatbots across various platforms.

```APIDOC
Atomese Agent Framework Design Goals:
  - Interact with environment: reading, writing, seeing, hearing.
  - Read text files in local file system.
  - Read directory contents and navigate directories.
  - Function as a chatbot (e.g., IRC, web-page JavaScript, Twitter, Discord, YouTube).
  - Goal: Prove lowest layers (glue) to convert external data into Atomese Atoms for higher-layer agents.
```

--------------------------------

### OpenLink API for Creating I/O Streams

Source: https://github.com/opencog/sensory/blob/master/Design.md

Defines the syntax for opening sensory streams. It takes a TypeNode specifying the stream type (e.g., TextFileStream) and a SensoryNode with connection details.

```lisp
(OpenLink
    (TypeNode 'FoobarStream) ; e.g. TextFileStream or IRChatStream
    (SensoryNode "url://of/some/sort")) ; e.g file:// or irc://
```

--------------------------------

### AtomSpace Bridge API

Source: https://github.com/opencog/sensory/blob/master/README.md

Describes the AtomSpace Bridge, an API designed to facilitate interaction between the AtomSpace and SQL databases. It aims to conform to system design but requires porting to current interfaces.

```APIDOC
AtomSpace Bridge:
  - Provides an API between the AtomSpace and SQL.
  - Almost conforms to the system design.
  - Requires porting over to the interfaces here.
  - Repository: https://github.com/opencog/atomspace-bridge
```

--------------------------------

### Atomspace Streaming Concepts

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-A.md

Explains the generic flow of atomspace code for generating values and converting them into streams. It details the roles of Gen, FutureStream, Promise, and how filtering can be applied to these structures.

```APIDOC
Generic Atomspace Flow:

1.  Generators (Gen):
    An Atom that generates new values upon execution.
    Example: `(Time)`

2.  FutureStream:
    Converts a generator function into a streaming value.
    Example: `(define fs (FutureStream (Time)))`
    Usage: `(cog-value->list fs)`

3.  Promise:
    Stores a streaming value (like FutureStream) in the AtomSpace.
    Example: `(define p (Promise (TypeNode 'FutureStream) f))`
    Usage: `(cog-execute! p)` returns `fs`.

4.  Filtering Streams:
    Filtering can be applied to the output of a promise.
    Example: `(define f (Filter (Rule...) (Promise ...)))`
    `f` can then be used as a streaming source.

5.  ValueOf:
    Behaves like a promise, allowing filtering to be applied directly.
    Example: `(define f (Filter (Rule...) (ValueOf ...)))
    Example: `(define p (Promise (TypeNode 'FutureStream) f))`
```

--------------------------------

### Grammar Notation Comparison

Source: https://github.com/opencog/sensory/blob/master/Architecture.md

Compares Link Grammar (LG) notation using +/- for direction with other grammar formalisms like pregroup grammars and CCG which use forward and backslashes (e.g., S/NP, VP\S) to indicate type constructors and direction.

```APIDOC
Link Grammar (LG) Notation:
  S- & O+
    - Represents a transitive verb connecting to a subject (S) and an object (O).
    - '-' indicates input, '+' indicates output.

Pregroup/CCG Notation:
  S/NP
    - Type constructor indicating a type that requires an NP on the right.
  VP\S
    - Type constructor indicating a type that requires an S on the left.
```

--------------------------------

### C++ Stream Implementations

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-A.md

Provides C++ class definitions for abstracting stream writing operations. OutputStream defines a virtual interface, and TextFileStream implements it for writing to a file handle.

```C++
class OutputStream
{
public:
	virtual ValuePtr write_out(const Handle&) = 0;
};

// Renamed version of PhraseStream today
class TextFileStream : public OutputStream
{
private:
	FILE* _fh;

public:
	ValuePtr write_out(const Handle& cref)
   {
		ValuePtr content =  cref->execute();
		StringValuePtr sv = StringValueCast(content);
		fprintf(_fh, "%s", sv->get_value());

		return sv;
	}
};

ValuePtr WriteLink::execute()
{
	TextStreamPtr = TextStreamCast(_outgoing[0]->execute());
	return ->write_out(_outgoing[1]);
}
```

--------------------------------

### Unification-based Stream Comparison

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-G.md

Illustrates how stream comparison can be conceptually framed using unification, specifically by checking the size of a unification result. This approach is more verbose than a dedicated StreamEqual link.

```Scheme
(Not (Equal (Number 0) (SizeOf (Unifier A B))))
```

--------------------------------

### C++ Sensory I/O Interface Design

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-A.md

Outlines the C++ class structure for a sensory I/O interface, including abstract base classes for nodes and streams, and concrete implementations for file handling.

```cpp
class TextStream
	: public LinkStreamValue
{
	virtual void update() const = 0;
};

// Renamed version of PhraseStream today
class TextFileStream : public TextStream
{
private:
	FILE* _fh;

	TextFileStream(std::string& file_to_open);

public:
	void update()
	{
		fread (_fh, ...);
	}
};
```

```cpp
class SensoryNode
{
	virtual ValuePtr make_new_read_iterator() = 0;
};

class TextFileNode : public SensoryNode
{
	ValuePtr make_new_read_iterator()
	{
		return createTextTextFileStream(_name);
	}
}
```

```cpp
ValuePtr ReadLink::execute()
{
	SensoryNodeCast(_outgoing[0])->make_new_read_iterator();
}
```

```cpp
ValuePtr WriteLink::execute()
{
	return SensoryNodeCast(_outgoing[0])->write_stuff(_outgoing[1]);
}

class SensoryNode
{
	virtual ValuePtr write_stuff(const Handle&) = 0;
};

class TextFileNode : public SensoryNode
{
	ValuePtr write_stuff(const Handle& args)
   {
		// Beta reduce and execute and etc.
		ValuePtr vargs = args->execute();
		fwrite(_fh, ..., vargs);
		return vargs;
	}
}
```

--------------------------------

### IRC Stream Open Command Description

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-B.md

Details the structure for opening an IRC chat stream, specifying the command to send and the target sensory node (URL).

```lisp-like
(Section
		(Item "this is our Open command")
		(ConnectorSeq
			(Connector
				(Sex "command")
				(Type 'OpenLink))
			(Connector
				(Sex "command")
				(Type 'SensoryNode))))
```

--------------------------------

### OpenLink Distribution Over Lists (Auto Unwrapping)

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-F.md

Demonstrates a design choice where OpenLink automatically distributes its operation over a list of SensoryNodes. This approach creates a separate FileSysStream for each item in the input list, potentially leading to a large number of streams.

```Atomese
(OpenLink (Type 'FileSysStream)
   (LinkValue
      (SensoryNode "file:///etc/vim")
      (SensoryNode "file:///etc/opt")
      (SensoryNode "file:///etc/nvme")
      (SensoryNode "file:///etc/ldap")
      (SensoryNode "file:///etc/lvm")))
```

--------------------------------

### Directory Listing with SensoryNodes

Source: https://github.com/opencog/sensory/blob/master/DesignNotes-F.md

Shows the conversion of StringValue directory paths into SensoryNode objects. This transformation is a prerequisite for applying further operations and examining the contents of these directory entries.

```Atomese
(LinkValue
   (SensoryNode "file:///etc/vim")
   (SensoryNode "file:///etc/opt")
   (SensoryNode "file:///etc/nvme")
   (SensoryNode "file:///etc/ldap")
   (SensoryNode "file:///etc/lvm"))
```

--------------------------------

### WriteLink API for Writing to Streams

Source: https://github.com/opencog/sensory/blob/master/Design.md

Defines the syntax for writing data to an existing I/O stream. It requires an iterator to the stream and the data to be written.

```lisp
(WriteLink
    (TextStream)   ; iterator to write to.
    (StringValue)) ; strings to write
```

--------------------------------

### Add Subdirectories to Build

Source: https://github.com/opencog/sensory/blob/master/opencog/atoms/CMakeLists.txt

This command is used within a build system to include subdirectories in the project's build process. It takes a directory name as an argument, ensuring that the contents of that directory are processed by the build tools.

```buildscript
ADD_SUBDIRECTORY (filedir)
ADD_SUBDIRECTORY (irc)
ADD_SUBDIRECTORY (sensory)
ADD_SUBDIRECTORY (terminal)
```