pushmac.pshm.1

#pushmac=
.B pushmac
@
#version=0.0.1@
.TH pushmac 1 2019-03-03 
.SH NAME
pushmac \- a stack-based macro processor that can form macros based on results returned by scheme functions
.SH SYNOPSIS #pushmac~
.SH DESCRIPTION #pushmac~is a stack-based macro processor.  It reads from standard input, evaluates the macros provided to standard input, and writes the processed text to standard output.  The macro language is parsed by reading one character at a time from left to right in a single pass.

.LP
The macro language is centered around a stack.  When you are on the bottom of the stack, characters typed in are echoed to standard output until a command is reached.  You can move up a level in the stack by using the PUSH command (by default: `#').  Text you enter at higher levels of the stack will not be put to standard output but can be accessed by #pushmac~commands.

.LP
Macro processing languages are used for text generation whether that text is code, a website, or writing.

.SH COMMANDS

The following are the #pushmac~commands.  These characters will just be output as is if there are not enough "levels" in the stack.  So most of these do not need to be escaped unless the stack already has some elements on it.
.TP
.BR `#'
PUSH command.  All text written after the command is the next level up on the stack.
.TP
.BR `@'
DEFINE command.  Pops the text off the top two levels of the stack and assigns the text at the top of the text to the macro name at the second level from the top.
.TP
.BR `~'
REFERENCE command.  Pops the text from the top of the stack, looks up the name of the macro specified there, and puts that text's value to the next level down in the stack.
.TP
.BR `$'
EXPAND command.  Expands the macros in the text on the top level of the stack.
.TP
.BR `|'
SHELL command.  Evalutes the text on the top level of the stack as a shell command, and outputs the output of the command to the next level down on the stack.
.TP
.BR '='
PUSH2 command. 
.TP
.BR ``text''
QUOTE text.  Put the literal text to the current level of the stack.  This is how you escape the command characters.
.TP
.BR `?'
QUESTION command. If the first element on the stack is "yes", output the second element on the stack, otherwise output the third element on the stack.
.TP
.BR `%'
IGNORE command.  Ignore everything on the top of the stack (i.e. this is like a "comment" command).
.TP
.BR `^'
SILENCE command. Do not print any of the characters on the top of the stack.
.TP
.BR `!'
SPEAK command.  Allow the characters (that presumably have been previously silenced) to print again.
.SH EXAMPLES
.LP
.BR "Section header"
.br
#pushmac~commands could be used to create a section header in a standard way, like so:
.RS
`#sec=`Section #i~: #title~''@
.br
`#i=1@
.br
#title=The Beginning@
.br
##sec~$
.br
#i=2@
.br
#title=After the Beginning@
.br
##sec~$'
.RE
are expanded to
.RS
Section 1: The Beginning
.br
Section 2: After the Beginning
.RE
This is useful in case you may want to change later how the titles are formatted.
.LP
.BR "Boilerplate Guile Code"

Guile is a Scheme language that is easy to use to extend programs. Guile functions have to be registered in the C program that wants to make use of them. #pushmac~makes this process easy to generate.  
.RS
  `#register=
.br
  void*
.br
  register_guile_functions (void* data)
.br  
  {@
.br  
  #gfunc=`#register##register~
.br  
  scm_c_define_gsubr("#name~", #argnum~, 0, 0, &guile_#name~);@
.br
  SCM
.br
  guile_#name~''`@
.br  
  #regbuild=`#register~
.br  
.br
  return NULL;
.br  
  }''`@'
.RE

Then, we can create guile functions like:
.RS
    `#name=myfunction@
.br
    #argnum=1@
.br    
    ##gfunc~$ (SCM file) { ... }'
.RE

And then type
.B "`##regbuild~$'"
to output the
.B register_guile_functions
function that can be used with Guile's
.B scm_with_guile
function.
.SH "SEE ALSO"
.SH BUGS
.TP
Please report as an issue to https://github.com/flynnzac/pushmac
.SH AUTHOR
Zach Flynn <zlflynn@gmail.com>
#version~