9 changed files with 0 additions and 445 deletions
-
6website/content/notes/business-communication.md
-
6website/content/notes/computer-science.md
-
6website/content/notes/finite-mathematics.md
-
30website/content/notes/literate-programming.md
-
179website/content/notes/plantuml.md
-
6website/content/notes/systems-analysis-design.md
-
112website/content/notes/thinking-in-cpp.md
-
16website/content/posts/hello.md
-
84website/content/posts/immutable-emacs.md
@ -1,6 +0,0 @@ |
|||||
+++ |
|
||||
title = "Business Communication" |
|
||||
author = ["Christopher James Hayward"] |
|
||||
lastmod = 2021-02-03T16:11:29-05:00 |
|
||||
draft = true |
|
||||
+++ |
|
||||
@ -1,6 +0,0 @@ |
|||||
+++ |
|
||||
title = "Computer Science" |
|
||||
author = ["Christopher James Hayward"] |
|
||||
lastmod = 2021-02-03T16:11:45-05:00 |
|
||||
draft = true |
|
||||
+++ |
|
||||
@ -1,6 +0,0 @@ |
|||||
+++ |
|
||||
title = "Finite Mathematics" |
|
||||
author = ["Christopher James Hayward"] |
|
||||
lastmod = 2021-02-03T16:12:05-05:00 |
|
||||
draft = true |
|
||||
+++ |
|
||||
@ -1,30 +0,0 @@ |
|||||
+++ |
|
||||
title = "Literate Programming" |
|
||||
author = ["Christopher James Hayward"] |
|
||||
lastmod = 2021-02-04T16:53:42-05:00 |
|
||||
draft = false |
|
||||
+++ |
|
||||
|
|
||||
- Programming paradigm |
|
||||
- Programs expressed in natural language with code snippets |
|
||||
- Produces machine readable code and human readable documentation |
|
||||
|
|
||||
|
|
||||
## Introduction {#introduction} |
|
||||
|
|
||||
Described in its introduction[^fn:1] as a |
|
||||
|
|
||||
> Programming paradigm in which a computer program is given an explanation of its logic in a natural language, such as English, interspersed with snippets of macros and traditional source code, from which compilable source code can be generated. |
|
||||
|
|
||||
The overal concept is not to difficult to imagine: |
|
||||
|
|
||||
{{< figure src="/ox-hugo/literate-programming-concept.png" >}} |
|
||||
|
|
||||
Knuth describes a **practitioner** in the introduction of his 1984 paper[^fn:1] as |
|
||||
|
|
||||
> An essayist concerned with exposition and excellence of style. Someone who carefully selects the name for each variable and describes their meaning. They will strive for a program that is comprehensible because concepts are introduced in a manner best for human understanding. |
|
||||
|
|
||||
|
|
||||
## Resources {#resources} |
|
||||
|
|
||||
[^fn:1]: Knuth, D. E. (1984). Literate Programming. The Computer Journal, 27(2), 97–111. <https://doi.org/10.1093/comjnl/27.2.97> |
|
||||
@ -1,179 +0,0 @@ |
|||||
+++ |
|
||||
title = "PlantUML" |
|
||||
author = ["Christopher James Hayward"] |
|
||||
lastmod = 2021-02-04T14:39:22-05:00 |
|
||||
draft = false |
|
||||
+++ |
|
||||
|
|
||||
As described by the webiste[^fn:1]: |
|
||||
|
|
||||
> **PlantUML** is a component that allows you to quickly write UML and other data diagrams, using a simple and intuitive language. |
|
||||
|
|
||||
|
|
||||
## Display JSON data {#display-json-data} |
|
||||
|
|
||||
You can use the JSON format with PlantUML to visualize your data, to activate the feature the diagram must use the `@startjson` and `@endjson` tags, respectively[^fn:2]. |
|
||||
|
|
||||
```plantuml |
|
||||
@startjson |
|
||||
"Hello world!" |
|
||||
@endjson |
|
||||
``` |
|
||||
|
|
||||
{{< figure src="/ox-hugo/plantuml-display-json-data.png" >}} |
|
||||
|
|
||||
|
|
||||
### Simple example {#simple-example} |
|
||||
|
|
||||
Here's an example of a `user` object, with an accompanying `address` and list of `phone` numbers: |
|
||||
|
|
||||
```plantuml |
|
||||
@startjson |
|
||||
{ |
|
||||
"name": "Bob", |
|
||||
"email": "bob@bob.com", |
|
||||
"phone": [ |
|
||||
{ "type": "work", "number": "555-1234" }, |
|
||||
{ "type": "mobile", "number": "555-4321" } |
|
||||
], |
|
||||
"address": { |
|
||||
|
|
||||
} |
|
||||
} |
|
||||
@endjson |
|
||||
``` |
|
||||
|
|
||||
{{< figure src="/ox-hugo/plantuml-display-json-data-simple-example.png" >}} |
|
||||
|
|
||||
|
|
||||
### Complex example {#complex-example} |
|
||||
|
|
||||
Here is the example of a complex data structure[^fn:2], which comes from the Wikipedia page for JSON[^fn:3]: |
|
||||
|
|
||||
```plantuml |
|
||||
@startjson |
|
||||
{ |
|
||||
"firstName": "John", |
|
||||
"lastName": "Smith", |
|
||||
"isAlive": true, |
|
||||
"age": 27, |
|
||||
"address": { |
|
||||
"streetAddress": "21 2nd Street", |
|
||||
"city": "New York", |
|
||||
"state": "NY", |
|
||||
"postalCode": "10021-3100" |
|
||||
}, |
|
||||
"phoneNumbers": [ |
|
||||
{ |
|
||||
"type": "home", |
|
||||
"number": "212 555-1234" |
|
||||
}, |
|
||||
{ |
|
||||
"type": "office", |
|
||||
"number": "646 555-4567" |
|
||||
} |
|
||||
], |
|
||||
"children": [], |
|
||||
"spouse": null |
|
||||
} |
|
||||
@endjson |
|
||||
``` |
|
||||
|
|
||||
{{< figure src="/ox-hugo/plantuml-display-json-data-complex-example.png" >}} |
|
||||
|
|
||||
|
|
||||
## Display YAML data {#display-yaml-data} |
|
||||
|
|
||||
Much like JSON, PlantUML can visualize YAML data using the `@startyaml`, and `@endyaml` keywords[^fn:4]: |
|
||||
|
|
||||
```plantuml |
|
||||
@startyaml |
|
||||
fruit: Apple |
|
||||
size: Large |
|
||||
@endyaml |
|
||||
``` |
|
||||
|
|
||||
{{< figure src="/ox-hugo/plantuml-display-yaml-data.png" >}} |
|
||||
|
|
||||
|
|
||||
### Docker example {#docker-example} |
|
||||
|
|
||||
Here's an example docker compose file running with a simple application structure[^fn:5]: |
|
||||
|
|
||||
```plantuml |
|
||||
@startyaml |
|
||||
version: "3.9" |
|
||||
|
|
||||
services: |
|
||||
db: |
|
||||
image: postgres |
|
||||
environment: |
|
||||
- POSTGRES_DB=postgres |
|
||||
- POSTGRES_USER=postgres |
|
||||
- POSTGRES_PASSWORD=postgres |
|
||||
web: |
|
||||
build: . |
|
||||
command: python manage.py runserver 0.0.0.0:8000 |
|
||||
volumes: |
|
||||
- .:/code |
|
||||
ports: |
|
||||
- "8000:8000" |
|
||||
depends_on: |
|
||||
- db |
|
||||
@endyaml |
|
||||
``` |
|
||||
|
|
||||
{{< figure src="/ox-hugo/plantuml-display-yaml-data-docker-example.png" >}} |
|
||||
|
|
||||
|
|
||||
## Sequence Diagram {#sequence-diagram} |
|
||||
|
|
||||
Here's the complete example[^fn:6] showing many participants. |
|
||||
|
|
||||
```plantuml |
|
||||
@startuml |
|
||||
/' |
|
||||
' Define the participant(s). |
|
||||
'/ |
|
||||
participant participant as 1 |
|
||||
actor actor as 2 |
|
||||
boundary boundary as 3 |
|
||||
control control as 4 |
|
||||
entity entity as 5 |
|
||||
database database as 6 |
|
||||
collections collections as 7 |
|
||||
queue queue as 8 |
|
||||
/' |
|
||||
' Draw a line to each participant(s). |
|
||||
'/ |
|
||||
1 -> 2 : To actor |
|
||||
1 -> 3 : To boundary |
|
||||
1 -> 4 : To control |
|
||||
1 -> 5 : To entity |
|
||||
1 -> 6 : To database |
|
||||
1 -> 7 : To collection |
|
||||
1 -> 8 : To queue |
|
||||
@enduml |
|
||||
``` |
|
||||
|
|
||||
{{< figure src="/ox-hugo/plantuml-sequence-diagram.png" >}} |
|
||||
|
|
||||
Here's a list of all the available keywords: |
|
||||
|
|
||||
- actor |
|
||||
- boundary |
|
||||
- control |
|
||||
- entity |
|
||||
- database |
|
||||
- collections |
|
||||
- queue |
|
||||
|
|
||||
|
|
||||
## Resources {#resources} |
|
||||
|
|
||||
[^fn:1]: PlantUML Website <https://plantuml.com> |
|
||||
[^fn:2]: PlantUML JSON Data <https://plantuml.com/json> |
|
||||
[^fn:3]: Wikipedia entry for JSON <https://en.wikipedia.org/wiki/JSON> |
|
||||
[^fn:4]: PlantUML YAML Data <https://plantuml.com/yaml> |
|
||||
[^fn:5]: Docker compose documentation <https://docs.docker.com/compose/django/> |
|
||||
[^fn:6]: PlantUML Sequence Diagrams <https://plantuml.com/sequence-diagram> |
|
||||
@ -1,6 +0,0 @@ |
|||||
+++ |
|
||||
title = "Systems Analysis & Design" |
|
||||
author = ["Christopher James Hayward"] |
|
||||
lastmod = 2021-02-03T16:12:26-05:00 |
|
||||
draft = true |
|
||||
+++ |
|
||||
@ -1,112 +0,0 @@ |
|||||
+++ |
|
||||
title = "Thinking in C++" |
|
||||
author = ["Christopher James Hayward"] |
|
||||
lastmod = 2021-02-03T14:08:28-05:00 |
|
||||
draft = false |
|
||||
+++ |
|
||||
|
|
||||
## Coding Style {#coding-style} |
|
||||
|
|
||||
**Eckel** justifies the decisions about the coding styles in the text[^fn:1]: |
|
||||
|
|
||||
> All the decisions about coding style in this book have been deliberately considered and made, sometimes over a period of years. |
|
||||
|
|
||||
|
|
||||
### General {#general} |
|
||||
|
|
||||
The coding style as described by **Eckel** is one that he came to after years of practice, and originates from Bjarne Stroustrup's style, the Author of `C++`[^fn:1]: |
|
||||
|
|
||||
> I use a particular coding style for the examples in this book. It was developed over a number of years, and was partially inspired by Bjarne Stroustrup's style in his original The C++ Programming Language. |
|
||||
|
|
||||
**Eckel** goes on to declare that it's more important to keep a consistent style, than to try to determine which is superior[^fn:1]: |
|
||||
|
|
||||
> Because C++ is a free-form programming language, you can continue to use whatever style you're comfortable with. That said, I will note that it is important to have a consistent formatting style within a project. |
|
||||
|
|
||||
|
|
||||
### File names {#file-names} |
|
||||
|
|
||||
**Eckel** describes the history of the naming conventions for `C/C++` files[^fn:1]: |
|
||||
|
|
||||
> In C, it has been traditional to name header files (containing declarations) with an extension of .h and implementation files (that cause storage to be allocated and code to be generated) with an extension of .c. |
|
||||
|
|
||||
Depending on the type of operating system, some files had different extensions as well[^fn:1]: |
|
||||
|
|
||||
> DOS C++ vendors used extensions of hxx and cxx for header files and implementation files, respectively, or hpp and cpp. Later, someone figured out that the only reason you needed a different extension for a file was so the compiler could determine whether to compile it as a C or C++ file |
|
||||
|
|
||||
| Name | Extension | Description | |
|
||||
|----------------|-----------|-----------------------------| |
|
||||
| Header | .h | Header files for C/C++ | |
|
||||
| Header | .hxx | Header file for C++ on DOS | |
|
||||
| Implementation | .c | Implementation file for C | |
|
||||
| Implementation | .cpp | Implementaiton file for C++ | |
|
||||
|
|
||||
|
|
||||
### Begin and end comment tags {#begin-and-end-comment-tags} |
|
||||
|
|
||||
Most of the code examples in the text book have comment tags at the beginning and end, which is part of a system used by **Eckel** to verify all of the code examples[^fn:1]: |
|
||||
|
|
||||
> A very important issue with this book is that all code that you see in the book must be verified to be correct (with at least one compiler). |
|
||||
|
|
||||
**Eckel** further elaborates how each example has a custom `makefile` and some program information included in the tags[^fn:1]: |
|
||||
|
|
||||
> Because ExtractCode.cpp also creates a makefile for each subdirectory, information about how a program is made and the command-line used to test it is also incorporated into the listings. |
|
||||
|
|
||||
|
|
||||
### Parentheses, braces, and indentation {#parentheses-braces-and-indentation} |
|
||||
|
|
||||
The section begins with, what is in my opinion, an accurate statement by **Eckel**, although not without irony[^fn:1]: |
|
||||
|
|
||||
> Of course, everyone thinks their own style is the most rational. However, the style used here has a simple logic behind it, which will be presented here mixed in with ideas on why some of the other styles developed. |
|
||||
|
|
||||
On addressing indentation[^fn:1]: |
|
||||
|
|
||||
> Everyone seems to agree that code inside braces should be indented. |
|
||||
|
|
||||
**Eckel** addresses braces in his coding style[^fn:1]: |
|
||||
|
|
||||
> ... the opening brace should always go on the same line as the "precursor" (by which I mean "whatever the body is about: a class, function, object definition, if statement, etc."). This is a single, consistent rule I apply to all of the code I write, and it makes formatting much simpler. |
|
||||
|
|
||||
|
|
||||
### Identifier names {#identifier-names} |
|
||||
|
|
||||
**Eckel** explains the naming conventions of identifiers[^fn:1]: |
|
||||
|
|
||||
> Those familiar with Java will notice that I have switched to using the standard Java style for all identifier names. However, I cannot be completely consistent here because identifiers in the Standard C and C++ libraries do not follow this style |
|
||||
|
|
||||
| Type | Style | |
|
||||
|---------------------|-------------| |
|
||||
| Class | Pascal Case | |
|
||||
| Function / Variable | Camel Case | |
|
||||
| Const / Definition | Snake Case | |
|
||||
|
|
||||
```cpp |
|
||||
class FrenchVanilla : public IceCream { } |
|
||||
``` |
|
||||
|
|
||||
```cpp |
|
||||
const MAX_SCOOPS = 3; |
|
||||
``` |
|
||||
|
|
||||
```cpp |
|
||||
FrenchVanilla myIceCreamCone(MAX_SCOOPS); |
|
||||
``` |
|
||||
|
|
||||
|
|
||||
### Order of header inclusion {#order-of-header-inclusion} |
|
||||
|
|
||||
**Eckel** broadly defines the order of inclusion[^fn:1]: |
|
||||
|
|
||||
> Headers are included in order from "the most specific to the most general." That is, any header files in the local directory are included first, then any of my own "tool" headers, such as require.h, then any third-party library headers, then the Standard C++ Library headers, and finally the C library headers. |
|
||||
|
|
||||
```cpp |
|
||||
#include <myheader.h> // Local directory headers. |
|
||||
#include <mytools> // Personal tool headers. |
|
||||
#include <thirdparty> // Third party library headers. |
|
||||
#include <bits/stdc++> // C++ library headers. |
|
||||
#include <iostream> // C library headerts |
|
||||
``` |
|
||||
|
|
||||
|
|
||||
## Resources {#resources} |
|
||||
|
|
||||
[^fn:1]: Eckel, Bruce. Thinking in C++. 2nd ed, Prentice Hall, 2000, <https://online.vitalsource.com/books/9781269392440>. |
|
||||
@ -1,16 +0,0 @@ |
|||||
+++ |
|
||||
title = "Hello, world!" |
|
||||
author = ["Christopher James Hayward"] |
|
||||
date = 2021-01-17 |
|
||||
lastmod = 2021-02-01T16:10:18-05:00 |
|
||||
draft = false |
|
||||
+++ |
|
||||
|
|
||||
```c |
|
||||
#include <stdio.h> |
|
||||
|
|
||||
int main() { |
|
||||
printf("Hello, world!"); |
|
||||
return 0; |
|
||||
} |
|
||||
``` |
|
||||
@ -1,84 +0,0 @@ |
|||||
+++ |
|
||||
title = "Immutable Emacs" |
|
||||
author = ["Christopher James Hayward"] |
|
||||
date = 2021-01-19 |
|
||||
lastmod = 2021-02-01T16:10:13-05:00 |
|
||||
draft = false |
|
||||
+++ |
|
||||
|
|
||||
You can easily create an **Immutable** and **100% Reproducible** custom Emacs configuration with very little effort. My inspiration for this came from the `Emacs From Scratch` series by [System Crafters](https://youtube.com/c/SystemCrafters). |
|
||||
|
|
||||
|
|
||||
## Getting started {#getting-started} |
|
||||
|
|
||||
Emacs created **lots** of files relative to `user-emacs-directory`, which are **not** part of this configuration and do not belong in the same directory. |
|
||||
|
|
||||
- Disable lockfiles |
|
||||
- Disable backup files |
|
||||
|
|
||||
To acheive this functionality, before anything else happens we change this directory to `~/.cache/emacs`, while keeping the old value of `user-emacs-directory` in our own variable. |
|
||||
|
|
||||
```emacs-lisp |
|
||||
(defvar dotfiles/home user-emacs-directory) |
|
||||
(defvar dotfiles/cache "~/.cache/emacs") |
|
||||
|
|
||||
(setq create-lockfiles nil |
|
||||
make-backup-files nil |
|
||||
user-emacs-directory dotfiles/cache) |
|
||||
``` |
|
||||
|
|
||||
|
|
||||
## Package management {#package-management} |
|
||||
|
|
||||
[Straight](https://github.com/raxod502/straight.el) is a 100% functional package manager for Emacs, with integration for `use-package`, a common way to download / configure / install Emacs packages. |
|
||||
|
|
||||
- Use the development branch |
|
||||
- Integrate with `use-package` |
|
||||
|
|
||||
Apply the configurations prior to bootstrapping the package manager, by setting (writing) to the variables that `straight` will ultimately read from. |
|
||||
|
|
||||
```emacs-lisp |
|
||||
(setq straight-repository-branch "develop" |
|
||||
straight-use-package-by-default t) |
|
||||
``` |
|
||||
|
|
||||
Bootstrap the package manager, downloading, installing, or configuring depending on the state of the configuration. All packages are downloaded and built from source, and can be pinned to specific git commit hashes. |
|
||||
|
|
||||
```emacs-lisp |
|
||||
(defvar bootstrap-version) |
|
||||
(let ((bootstrap-file |
|
||||
(expand-file-name "straight/repos/straight.el/bootstrap.el" user-emacs-directory)) |
|
||||
(bootstrap-version 5)) |
|
||||
(unless (file-exists-p bootstrap-file) |
|
||||
(with-current-buffer |
|
||||
(url-retrieve-synchronously |
|
||||
"https://raw.githubusercontent.com/raxod502/straight.el/develop/install.el" |
|
||||
'silent 'inhibit-cookies) |
|
||||
(goto-char (point-max)) |
|
||||
(eval-print-last-sexp))) |
|
||||
(load bootstrap-file nil 'nomessage)) |
|
||||
``` |
|
||||
|
|
||||
Complete the integration with `use-package` by installing it with `straight-use-package`: |
|
||||
|
|
||||
```emacs-lisp |
|
||||
(straight-use-package 'use-package) |
|
||||
``` |
|
||||
|
|
||||
|
|
||||
## A E S T H E T I C S {#a-e-s-t-h-e-t-i-c-s} |
|
||||
|
|
||||
If you've ever looked at default Emacs, you know that it's one of the ugliest GUI applications out of the box. Including a few packages, cherry picked from `Doom` can bring Emacs out of the eightes! |
|
||||
|
|
||||
```emacs-lisp |
|
||||
(use-package all-the-icons) |
|
||||
(use-package doom-modeline :init (doom-modeline-mode 1)) |
|
||||
(use-package doom-themes :init (load-theme 'doom-one t)) |
|
||||
``` |
|
||||
|
|
||||
|
|
||||
## Conclusion {#conclusion} |
|
||||
|
|
||||
Now that the **stateful** and **immutable** files are seperated, and the default look has been improved **slightly** you're left with a clean, immutable, and reproducible Emacs configuration to continue hacking on. |
|
||||
|
|
||||
Enjoy it! |
|
||||
Write
Preview
Loading…
Cancel
Save
Reference in new issue