edgecase
Author: StJohn Piano
This page is subject to change at any time. It is not signed by its author or by Edgecase Datafeed.
748 words - 387 lines - 10 pages





The basic way to display code when writing an article is to enclose it within a
code
element. This is for code / data snippets and for the names of variables or tools. The
code
element will distinguish these visually from the surrounding text.

Example:

The <code>curl</code> tool can be used to download a webpage, like so:
<code>curl http://edgecase.net/articles/0</code>


This will be rendered as:

The
curl
tool can be used to download a webpage, like so:
curl http://edgecase.net/articles/0





When writing, it is often easier to use
code_lines
instead, which can have a newline before and after the enclosed item, making the result easier to read and check.

Example:

The <code>curl</code> tool can be used to download a webpage, like so:
<code_lines>
curl http://edgecase.net/articles/0
</code_lines>


This will be rendered as:

The
curl
tool can be used to download a webpage, like so:
curl http://edgecase.net/articles/0





The more complex way to display code is to use a
lined_code
element. This is designed to format a block of code (or an entire code file) for a web page in a readable way that can be manually copied / downloaded by the reader. The code itself should not be altered in any way, but simply copied into a new
lined_code
element, into the line just after the
data_lines
element.

Example:

<lined_code>
<code_title>Hello World in Python</code_title>
<language>python_2.7.13</language>
<line_numbers>yes</line_numbers>
<link>
<type>asset</type>
<filename>hello_world.py</filename>
<text>[download this code]</text>
<sha256>a73a174cc9d68c2351153c7f2324690b80c9b58b46a7fef605ee9b5f3be12ed6</sha256>
</link>
<data_lines>
#!/opt/local/bin/python

print "hello world"
</data_lines>
</lined_code>


Note: The asset link used here does not actually work. It is just an example.

This will be rendered as:

Hello World in Python

python 2.7.13

[download this code]
#!/opt/local/bin/python

print "hello world"



To avoid displaying line numbers, don't include the
line_numbers
element.

The
link
element is optional. If it is used, the code must be saved in a file and included as an asset of the article. This is for when the code is designed as a building block that will be used in the future. If it is just an example, made for illustration, there is no need to make it into an asset.

The
title
and
language
elements are also both optional.





If the
line_numbers
element exists and contains "yes", there is another optional element that can be included:
<first_line_number>21</first_line_number>


This is for ensuring that the correct line numbers are used when displaying an excerpt of a code file.

Example:

<lined_code> <line_numbers>yes</line_numbers> <first_line_number>21</first_line_number> <data_lines> n = g.order() secret = randrange( 1, n ) pubkey = Public_key( g, g * secret ) privkey = Private_key( pubkey, secret ) </data_lines> </lined_code>


This will be rendered as:

  n = g.order()
  secret = randrange( 1, n )
  pubkey = Public_key( g, g * secret )
  privkey = Private_key( pubkey, secret )





Here are several longer examples:




parse.asd


<lined_code> <code_title>parse.asd</code_title> <language>Common_Lisp</language> <data_lines> (asdf:defsystem :parse :description "" :author "" :license "" :version "" :serial t :components ((:file "packages") (:file "error") (:file "scope") (:file "parse"))) </data_lines> </lined_code>


This will be rendered as:

parse.asd

Common Lisp
(asdf:defsystem :parse
  :description ""
  :author ""
  :license ""
  :version ""
  :serial t
  :components
    ((:file "packages")
     (:file "error")
     (:file "scope")
     (:file "parse")))





packages.lisp


<lined_code> <code_title>packages.lisp</code_title> <language>Common_Lisp</language> <line_numbers>yes</line_numbers> <data_lines> (defpackage :parse (:use :cl) (:export *root-scope* *active-scope* scope-error scope scope-name parent grandparent great-grandparent errors empty-p has-errors-p add-error close-scope execute-command print-scope content-scope content append-content container-scope children open-child keyword-scope parse)) </data_lines> </lined_code>


This will be rendered as:

packages.lisp

Common Lisp
(defpackage :parse
  (:use :cl)
  (:export
    *root-scope*
    *active-scope*
    scope-error
    scope
    scope-name
    parent
    grandparent
    great-grandparent
    errors
    empty-p
    has-errors-p
    add-error
    close-scope
    execute-command
    print-scope
    content-scope
    content
    append-content
    container-scope
    children
    open-child
    keyword-scope
    parse))





error.lisp


Note: The asset link used here does not actually work. It is just an example.

<lined_code> <code_title>error.lisp</code_title> <language>Common_Lisp</language> <line_numbers>yes</line_numbers> <link> <type>asset</type> <filename>error.lisp</filename> <text>[download this code]</text> <sha256>a73a174cc9d68c2351153c7f2324690b80c9b58b46a7fef605ee9b5f3be12ed6</sha256> </link> <data_lines> (in-package :parse) (defclass scope-error () ((value :initarg :value :initform nil :accessor value))) (defclass no-function-error (scope-error) ((name :initarg :name :reader name) (command :initarg :command :reader command))) (defmethod initialize-instance :after ((no-function-error no-function-error) &key) (setf (value no-function-error) (format nil "No function for command \"~A\" in scope ~A" (command no-function-error) (name no-function-error)))) (defun make-no-function-error (name command) (make-instance (quote no-function-error) :name name :command command)) </data_lines> </lined_code>


This will be rendered as:

error.lisp

Common Lisp

[download this code]
(in-package :parse)

(defclass scope-error ()
  ((value
     :initarg :value
     :initform nil
     :accessor value)))

(defclass no-function-error (scope-error)
  ((name
     :initarg :name
     :reader name)
   (command
     :initarg :command
     :reader command)))

(defmethod initialize-instance
  :after ((no-function-error no-function-error) &key)
  (setf
    (value no-function-error)
    (format nil "No function for command \"~A\" in scope ~A"
      (command no-function-error)
      (name no-function-error))))

(defun make-no-function-error (name command)
  (make-instance (quote no-function-error)
    :name name
    :command command))